kosh

kosh [options] [script [argument...]]kosh -c command [argument...]kosh -s [argument...]kosh --lint [-c command...] [file...]kosh --format [file]kosh --format --apply file...kosh --lint [--format] --apply file...kosh --language-server

kosh is the Koshka shell: a Bash 5.3- and Dash-compatible interpreter, interactive shell, formatter, and language server. Linux, macOS, and Windows are first-tier targets with equivalent grammar. The Linux binary is static and does not link the C++ standard library.Four moods select dialect and strictness. The default kosh mood is a strict Bash superset: analysis, pipefail, failglob, and nounset are on. bash accepts Bash extensions with analysis off by default. sh follows supported Dash behavior. bash-posix is Bash syntax with POSIX mode and Bash startup files. A binary named sh, dash, bash, or rbash picks the matching mood (and rbash also enables restricted mode). `set --mood` changes the mood at runtime.Before a command runs, Koshka analyzes and may fold constants or drop unreachable code. The catalog includes hundreds of built-in ShellCheck-derived checks plus native analysis. `kosh --lint` is the noninteractive reporter; `kosh --format` pretty-prints (two-space indent, 80-column wrap, `test` rewritten to `[` unless shadowed). `kosh --language-server` provides diagnostics, quick fixes, completion, navigation, semantic tokens, outline, hover, and rename over LSP.Interactive editing is fish-inspired and does not use readline: syntax highlighting, ghost text, UTF-8 width handling, multiline editing, and persistent history. Extra builtins include z (zoxide-style directory jump), bench (timing/RSS samples), and assimilate (copy this binary onto an SSH host). koshkit is a BusyBox-style bundle (`cat`, `cp`, `find`, `grep`, `ps`, `timeout`, and others) invoked as `koshkit` utility or, with --enable-koshkit, as those names directly.

-c, --command=COMMAND

Read and run COMMAND. Repeatable; strings run in occurrence order.

Read commands from standard input. Takes precedence over -c and a script operand.

Request an interactive session.

Request a login shell (also implied when argv0 starts with a dash).

Select kosh (default), bash, sh, or bash-posix. Aliases: default for kosh; posix and dash for sh.

Run a script under the mood matching its `sh`/`dash`/`bash` shebang. Current diagnostic settings are kept.

Source startup files for each comma-separated mood, in order. Default is the selected runtime mood.

Analyze without running (like -n with every diagnostic tier enabled). Skips startup files. With --apply, writes safe structured fixes and re-analyzes.

Format shell source without running it. No file or a lone - reads stdin; one named file is written to stdout. Combine with --apply to rewrite files.

Write lint fixes and/or formatted source into named files atomically. Rejects stdin, -s, -i, -c, and a lone -.

Speak LSP on stdin/stdout. Intended for editors; does not take file operands, -c, -s, -i, --lint, --format, or --apply.

Parse and analyze without executing.

Exit after an unguarded failing command (errexit).

Treat an unset variable read as an error.

Print each command after expansion.

Print each input line as it is read.

Do not overwrite an existing file with a plain `>` redirection.

Disable pathname expansion.

Control analysis severity. In the default mood, -W keeps strict/lenient findings as errors; -WW demotes lenient errors to warnings; -WWW also demotes strict errors. In other moods, -W/-WW/-WWW enable strict, then lenient, then annoying diagnostics as warnings.

Skip the analysis stage.

Suppress the annoying (style/noisy) tier only.

List analysis checks and exit.

Skip every startup file and set PATH to `/usr/bin:/bin`.

Equivalent to --mood sh, -T, and --no-diagnostics, with color off.

Restricted mode (PATH/SHELL/HISTFILE/ENV changes, directory changes, and most output redirections are refused after startup).

Privileged mode. Skip BASH_ENV; skip every startup file when real and effective ids differ.

Interactive rc file. Last occurrence wins. In the kosh mood it replaces `/etc/koshrc` and `~/.koshrc`.

Skip the interactive non-login Bash rc and a custom rc file.

Select the bash-posix mood.

Resolve bundled koshkit utility names as commands (`set -o koshkit`).

Disable tab completion and ghost text.

Disable syntax coloring and ghost text (completion remains).

Print help and exit.

Print version and notices and exit.

Print the short version and exit.

Startup files are ordinary shell source, parsed in the mood that selected them. See kosh(5)./etc/koshrc, ~/.koshrc

Interactive kosh mood rc files (after login profiles). Replaced as a pair by --rcfile.

Login files for kosh and sh moods.

Bash-mood login and interactive rc files, plus stock bash-completion when present.

Default command-line options, parsed before argv. A real flag still wins. -c, --format, --apply, and --language-server are discarded from this variable.

Command history file (default ~/.kosh_history).

Frecency store for the z builtin (default ~/.kosh_directory_history).

Extra startup path for interactive sh (ENV) and noninteractive bash (BASH_ENV). Privileged mode skips both.

Nonempty value disables prompt, diagnostic, and koshkit cat color.

Early-stage software; the authors warn it may still misbehave. Do not replace a production login shell without testing. Default kosh mood is much stricter than Bash: unquoted globs, unset reads, and many ShellCheck findings reject the script unless you demote them with -W/-WW/-WWW, switch mood, or add a `# shellcheck disable=` comment. Symlinking the binary as bash or sh disables diagnostics. --lint --apply only writes safe structured fixes. Debug-only flags (--debug-logging, --ftrace) are absent from release builds.

Written from scratch in a C++23 dialect compiled with -nostdlib++ (links only libc). The project began as a late April Fools' joke under the name shit; 0.2.0 renamed the shell to Koshka (koshka is Russian for cat) and the binary to kosh. BSD-3-Clause. Source: https://github.com/toiletbril/kosh.

bash(1), dash(1), fish(1), shellcheck(1), busybox(1), ksh(1)

Source code · Documentation