The whim Command

The whim program runs source, formats and lints it, prints bytecode, and manages Git dependencies.

Use whim --help or whim COMMAND --help for the installed version’s exact options.

Run

The short and explicit forms are equal:

whim app.whim one two
whim run app.whim one two

The first argument after the file has index zero in Whim\Env\get_arguments().

Use - as the file to read source from standard input:

printf "write_line!('hello');\n" | whim -

Source read this way cannot use embed! because it has no directory.

Global options must come before the source file:

Use -- before a source path that starts with -.

whim run reads the nearest whim.toml, loads the bundled standard-library artifact, then compiles the entry file and files that the program loads. It does not inspect whim.lock or vendor/.

Runtime settings belong in [runtime]:

[runtime]
optimizations = "on"
call-depth = 10000
cycle-threshold = 10001
full-trace = false

Each field is optional. For one run, use WHIM_OPTIMIZATIONS, WHIM_CALL_DEPTH, WHIM_CYCLE_THRESHOLD, or WHIM_FULL_TRACE. Environment values override the file:

WHIM_OPTIMIZATIONS=off whim app.whim
WHIM_FULL_TRACE=true whim app.whim

Format

whim fmt
whim fmt src/ tests/
whim fmt --check

With no paths, the command finds the nearest whim.toml and formats the project from that file’s directory. It skips vendor/ and .git/. A command with no paths fails when it cannot find a manifest.

The command also accepts files and directories. An explicit directory ignores format.include but honors exclusions. An explicit file bypasses both. --check reports files that would change and writes nothing.

Project selection belongs in [format]:

[format]
include = ["**/*.whim"]
exclude = ["src/generated/**"]

Patterns use / and are relative to the manifest directory. Exclusion wins. The default inclusion is **/*.whim; vendor/ and .git/ are always excluded from directory walks.

Layout settings can come from the nearest whim.toml, a file passed through the global --config option, or command options:

• --print-width N
• --tab-width N or --tab-size N
• --use-tabs true|false
• --end-of-line lf|crlf

Command options override file settings.

Disassemble

whim disassemble app.whim
WHIM_OPTIMIZATIONS=off whim disassemble app.whim
printf "write_line!('hello');\n" | whim disassemble -

This command compiles the program and prints its register bytecode. It does not run the entry file. WHIM_OPTIMIZATIONS=off prints the form before optimization.

Lint

whim lint
whim lint src/ tests/
whim lint --json src/ > lint.json

With no paths, whim lint finds the nearest whim.toml and checks that project. It uses the same file discovery as fmt, with separate lint.include and lint.exclude settings. Explicit directories ignore the inclusion list; explicit files bypass file filters. Per-rule exclusions still apply.

All 15 rules start enabled. The command prints source diagnostics and leaves files unchanged. Error-level findings, syntax errors, and file errors return a nonzero status. Lower levels still print; set lint.minimum_fail_level to make them fail the command too. --json writes diagnostics as a JSON array to standard output; logs stay on standard error. See Linting for the JSON fields, rules, and settings.

Language server

whim language-server

The language server speaks LSP over standard input and output. It provides keyword completion, snippets, formatting, folding, selection ranges, and lint and syntax diagnostics. It publishes diagnostics as open documents change and supports document and workspace diagnostic requests. Workspace checks use open buffers for unsaved files and read other files from disk. The server reads lint settings at startup; restart it after changing whim.toml. It does not provide symbol navigation.

Project commands

init, add, remove, install, and update change dependency state. show, why, suggestions, and fund inspect it. why-not tests a new requirement against the graph. It creates and locks the project cache and may fetch Git tags, so it needs a writable project and network access.

These commands search the current directory and its parents for whim.toml, except init, which creates a project in the current directory. whim init --no-git skips Git setup.

Package command failures leave the old manifest, lock, vendor tree, and loader together. See Git Dependencies.

Log output

WHIM_LOG sets the CLI log filter. WHIM_LOG=off disables all log output, including error-level records. A CLI command can therefore fail with no error text while still returning a nonzero status. This is intended.

Log errors are not Whim exceptions. Disabling log output does not catch or change a thrown value, an uncaught throwable, or a panic! trace.

lint and fmt log the selected file count and a final summary at info level. The summary includes clean files, changed files, findings by level, file errors, elapsed time, and whether the command failed. For fmt --check, changed files are files that need formatting. A file error does not stop checks on other files.

Use debug to inspect the loaded configuration, file filters, discovery totals, worker count, and pipeline duration. Use trace to see why paths were skipped, which lint rules are enabled, and how long each file spends in reading, parsing, linting or formatting, and reporting:

WHIM_LOG=whim=debug whim lint src/
WHIM_LOG=whim=trace whim fmt --check src/
WHIM_LOG=error whim lint src/

The whim= filter limits these logs to the CLI. Logs go to standard error; lint diagnostics and format diffs go to standard output in file discovery order. Directory entries are sorted by name. Trace records carry the command, batch, and file context across workers. Detailed phase timers run only at trace level.

The commands check output writes and the final buffer flush. If the receiving process closes a pipe, they stop reporting and exit successfully, as with whim lint src/ | head. Other output failures return a nonzero status.

Exit status

The CLI returns zero on success. exit!($status) selects another status. panic! and an uncaught throwable use 255. CLI errors return a nonzero status. CLI error text goes to standard error. Lint findings go to standard output. Program output goes to the handle used by its write calls.