CLI checks¶
The cli lints check a command-line tool against the practices of the CLI UX guide of vhrd_cli: help with examples, completion, --version, colour rules, machine-readable output and exit codes. They hold for any CLI built on clap; a CLI does not need vhrd_cli's crates to pass them.
How spl sees a CLI¶
spl builds the CLI and runs it, the way a person or a script meets it. It reads what the tool prints, not how the source spells it. A derive struct, the builder API and commands that register themselves through linkme all look the same from outside, and the checks see help text that clap assembles at run time, such as a flattened struct's documentation.
For each CLI binary, spl runs cargo build --message-format json -p CRATE --bins in the project and takes the executables cargo reports. It then starts each binary only with arguments that print and exit:
| Probe | What it shows |
|---|---|
BIN -h and BIN --help |
the command tree, one line per item, the long help |
BIN SUB -h and BIN SUB --help |
the same for every subcommand listed under Commands:, down to depth-max levels |
BIN --version |
the version line |
BIN --spirit-level-unknown-flag |
the answer to a usage error |
COMPLETE=bash BIN --help (and zsh, fish) |
the completion registration; a CLI without completion prints its help instead |
Each probe runs with a clean environment: only PATH, TERM=dumb, and a HOME and XDG directories inside an empty scratch directory, which is also the working directory. Standard input is closed and both outputs are pipes. A probe that does not exit within timeout-secs is killed and reported. Help, version and a usage error never reach the tool's own code in a clap CLI, so the probes change nothing outside the scratch directory.
The probe reads clap's help layout: a Usage: line, then sections such as Commands:, Arguments: and Options: with one indented entry per item. A binary whose help has no Usage: line is not a clap CLI, and its help lints are reported as not run.
Settings¶
The [cli] table of spirit_level.toml holds the settings every CLI lint shares. Each key is optional.
[cli]
timeout-secs = 10 # one run of a tool is killed after this long
depth-max = 4 # subcommand levels probed below the tool
commands-max = 1000 # commands probed per tool at most
build-args = ["--locked"] # more arguments to `cargo build`
target-dir = "target/cli-probe" # cargo's target directory, relative to the root (default: cargo's own)
commands-heading = "Commands:" # the help heading under which clap lists subcommands
The values above are the defaults, except build-args and target-dir, which are empty by default.
Which crates are CLIs¶
The crate map says it with the key cli (the crate map):
[map.crates]
foo_cli = { layer = "app", cli = true } # every binary of the crate is checked
foo_bench = { layer = "app", cli = false } # its binaries are left out
Without the key, or without a map, a workspace crate with a binary target and a dependency on clap is a CLI. A project without a map is therefore checked too, and a crate whose binary is not meant for people (a test helper, a server) is left out with cli = false.
vhrd_cli and any clap CLI¶
Every check holds for any clap CLI. vhrd_cli's crates make passing them cheap:
| Crate | What it gives | The lints it satisfies |
|---|---|---|
vc_build |
--version with SHA and commit time from a worktree-safe build script |
cli-version-line |
vc_ui |
a global --color, colour off without a terminal, the error line, the exit codes |
cli-color-flag, cli-plain-when-piped, cli-usage-error |
vc_complete |
dynamic completion for bash, zsh and fish, quiet on errors | cli-completion |
A CLI with its own build script or completion adapter passes the same checks when it prints the same thing. vhrd_cli's repo_checks crate checks vhrd_cli's own documents (the guide's path, sections and links); it looks at no CLI, so nothing here repeats it.
The catalogue¶
One row per practice of the guide: the section that states it, the lint that checks it, and how sure that lint is. by review means no lint can check the practice honestly; a reviewer checks it. Certain lints compare the tool's output with a rule. Estimate lints rest on an assumption that their message states.
| Practice | Guide | Checked by | How sure |
|---|---|---|---|
| A cut list names what it left out and the flag that shows the rest | §2 | by review | |
| A disabled action stays listed with its reason | §2 | by review | |
| Raw input is calibrated by measuring, then confirmed | §2 | by review | |
| A step says why it runs; ids are shown with their names | §2 | by review | |
Commands are noun verb, with the same verbs for every noun |
§3 | by review | |
| Flags over positional arguments | §3 | by review | |
Short flags keep their standard meaning (-n is --dry-run) |
§3 | cli-standard-flags | certain |
| Global flags work before and after the subcommand | §3 | cli-color-flag for --color; clap for the rest |
certain |
| No prefix abbreviations of subcommands | §3 | by review | |
| Secrets never come from a flag value | §3 | by review | |
Plugins live on PATH and show in help and completion |
§3 | by review | |
| Commands register themselves per module, with a registry test | §3 | by review | |
| The CLI is a thin crate over a library | §3 | third-party-placement, forbidden-closure, cli-subprocess | certain |
-h gives one line per item; every command and argument has help |
§4 | cli-help-text | certain |
--help of the tool and of every leaf command ends in Examples: |
§4 | cli-help-examples | certain |
| Help text is prose for the terminal, without rustdoc leftovers | §4 | cli-help-clean | certain |
-h works anywhere on the line |
§4 | clap | |
A next: hint goes to stderr when stdout is not a terminal |
§4 | by review | |
| A typo gets a suggestion and is not run | §4 | clap's suggestions feature |
|
| Completion for bash, zsh and fish, registered from the binary | §5 | cli-completion | certain |
| Completion offers live values, each with a help text | §5 | by review | |
Completion never falls back to file names (-o bashdefault) |
§5 | cli-completion | certain |
| Slow values come from a cache; plugins answer a probe; a picker on Tab | §5 | by review | |
| stdout carries the data, stderr everything else | §6 | print-in-library keeps printing in the binary; the rest by review | |
| Colour is off when the output is not a terminal | §6 | cli-plain-when-piped | certain |
A global --color auto\|always\|never |
§6 | cli-color-flag | certain |
NO_COLOR turns colour off |
§6 | by review: a pipe already turns it off | |
| One style set, few colours, red only for errors | §6 | by review | |
| Column widths are measured on the visible text | §6 | by review | |
Short, line-oriented output; dates as 7 Oct 2026 |
§6 | by review | |
| Every command has a machine-readable form | §6 | cli-json-output | estimate |
| JSON carries a version field; outside strings are escaped | §6 | by review | |
| A frame and a pager only at a terminal | §6 | by review | |
| An error is one stderr line that names the tool and what to do | §7 | by review | |
No unwrap on outside data |
§7 | panic-in-library in libraries; by review in the binary | certain |
| A failed step shows its last lines and the log path | §7 | by review | |
| A usage error exits with 2, on stderr only | §7 | cli-usage-error | certain |
| Exit codes 3-63 are documented; 75 and 78 keep their meaning | §7 | by review | |
| Under JSON output an error is one JSON line on stderr | §7 | by review | |
| Progress for any step over a few seconds | §8 | by review | |
| Deploys read like an installer; transfers send only what changed | §8 | by review | |
| Ctrl-C answers at once; network calls time out | §8 | by review | |
Prompts only at a terminal, each with a flag; --dry-run changes nothing |
§9 | by review | |
| Layered settings; every tunable is a typed setting | §10 | by review | |
--version prints tool 0.4.2 (a1b2c3d-dirty, commit 3 Oct 2026 18:20 UTC) |
§11 | cli-version-line | certain |
| The version comes from a worktree-safe build script without a clock | §11 | cli-version-line catches unknown from a git checkout |
certain |
| Libraries read build info at run time | build-info-env | certain | |
| Every invocation records its usage per subcommand | §11 | by review | |
| Every learnable feature lands in the skill tree | §11 | by review | |
| Tests cover help, completion, colour, exit codes and JSON | §12 | by review |
Levels¶
The shipped tiers enable the CLI lints from small on, because a single crate is often a CLI. The lints that fail rarely and point at a plain defect (cli-help-clean, cli-usage-error, cli-plain-when-piped) deny from medium on. The lints that ask for work in most existing CLIs (examples, help lines, completion, --color, the version line, standard flags) warn. cli-json-output is off: which commands print data is a judgement its estimate cannot make for every tool.