Review CLI
Review of the interface a command-line tool presents, not the language it is written in. The
checks below are the same for a Python CLI and a Rust one; only the fixes differ, and §8 carries
those.
Complements review-<language> skills (which review the code) and review-interfaces (which
reviews function and module signatures, not the CLI surface). Don't repeat either.
Review grading
Use only these finding priorities, in descending order:
- Critical Issues (Must Fix): a verified path causes data loss, a security failure, a materially
wrong operation, or makes a core workflow unusable without reasonable recovery.
- Improvements (Should Fix): an ordinary supported workflow demonstrably fails or repeatedly
imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.
- Suggestions (Nice to Have): a worthwhile improvement with small practical impact, including
optional polish, local simplification, and rare recoverable edge cases.
Grade the demonstrated consequence, realistic reachability, and available recovery against project
priorities. A category, missing convention, hypothetical future problem, or confidence that a claim
is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep
unverified claims in validation gaps, outside the graded finding count; distinguish suggestions
from defects. For plans, trace the consequence if implemented and state the assumptions.
Use the short labels Must Fix, Should Fix, and Nice to Have in summaries and ledgers.
Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings
separate. When called by code-review, return its requested evidence and impact fields; the parent
owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.
Relationship to the toolchain (read first)
There is essentially no tooling for this layer. That is not an assumption — a search across
four phrasings for a CLI-design linter turned up clig.dev itself, generic static-analysis
round-ups, and no tool. ShellCheck analyses shell scripts, i.e. programs written in bash; it says
nothing about the interface a compiled or Python program presents. Neither ruff nor clippy ships a
CLI-conventions rule set.
Two narrow exceptions worth knowing:
- Rust can mechanize the stream discipline in §2.
clippy::print_stdout and
clippy::print_stderr are restriction lints — off by default, but a crate can turn them on and
#[allow] the handful of genuine output sites. When reviewing a Rust CLI, recommend enabling
the lint rather than listing instances one by one.
clap::Command::debug_assert() catches duplicate short flags and conflicting requirements —
definition consistency, not design.
So this skill carries more weight than a language review does, and its findings must be earned
by evidence, since nothing else will catch a mistake here and nothing else will catch a false
positive either.
What this skill checks
A CLI's design is decided once; its behaviour regresses continuously. So the default review
looks only at what the diff introduces — a new subcommand, a new output path, a new destructive
operation, a new prompt. One-time properties (does --version exist, does --help carry
descriptions, are config roots XDG-correct) belong to the project-level set in §P, which runs
at --all and nowhere else. Re-checking those on every diff is noise, and it buries the findings
that matter.
Step 0: probe what the diff touches
Most CLI behaviour is invisible in the source, so run the thing rather than reading it — but scope
the probing to the change:
- Any scope: if the diff adds or changes an output path, pipe it into
head and check stderr
is empty. If it adds a destructive operation, run it with < /dev/null. If it adds --json
output, pipe it through jq.
--all only: the full probe table in §P.
The pipe probe needs output larger than the pipe buffer (~64 KB) or it silently passes. Use the
largest output the changed command can produce.
A probe you could not run (no build, no fixture data) is reported as not run, never as passing.
Usage
/review-cli # Review context-related code
/review-cli --staged # Review staged changes
/review-cli --unpushed # Review files changed across all unpushed commits
/review-cli --changed # Review unstaged changes
/review-cli --all # Full CLI surface audit (the natural scope for this skill)
/review-cli --multi # Also get external advisor opinions
Scope
| Flag |
Scope |
Method |
| (none) |
Context-related code |
Files from the current conversation context, plus the CLI entry point and argument definitions regardless of scope — a diff to one subcommand is reviewed against the whole interface it joins. |
--staged |
Staged changes |
git diff --cached --name-only |
--unpushed |
Files changed across unpushed commits |
git diff --name-only $(git rev-list HEAD --not --remotes | tail -1)^..HEAD |
--changed |
Unstaged changes |
git diff --name-only |
--all |
Whole CLI surface + §P project-level checks |
Entry point, argument definitions, every subcommand handler, output and prompt helpers |
--multi |
Add external opinions |
Combines with any scope above; invokes second-opinion --quick |
Only --all runs §P. At every other scope the review covers §1–§8 against what the diff
introduces, and a §P finding is out of scope even if you notice it — note it in one line at the end
if it is severe, but never as a review finding.
Workflow
Determine scope and locate the entry point and argument definitions.
Run the Step 0 probes. Record results.
Read AGENTS.md / CLAUDE.md / README — the README matters unusually much here, because a
gap between what it documents and what --help says is itself a finding (§6).
Review against §1–§7. Load references/conventions.md for the normative sources and the
contested list; load references/language-notes.md when writing a fix.
Parallelize if the CLI has many subcommands: one sub-agent per category, merge and dedupe.
External opinions (if --multi): invoke second-opinion --quick with this prompt:
Read-only review of a command-line tool's interface, not its implementation language. No
linter covers this layer, so nothing is out of scope for being mechanical. Focus on: does a
destructive command have a gate, and is whatever justifies skipping it available on every code
path that reaches it? Does the tool refuse rather than assume when stdin is not a terminal?
Does it ever report an action that did not happen? Do exit codes distinguish failure classes
without colliding? Is primary output on stdout and every diagnostic on stderr? Does a dry-run
flag reach the lowest write primitive or just the command handler? If it dies halfway, what is
left behind and is a re-run safe? Do errors say what to do next? 300 words or less.
Wait for all external results before proceeding.
Classify severity and report, grouped by severity.
1. Exit codes & signals
- Broken pipe is the single most commonly missed defect. A tool piped into
head keeps
writing after the reader exits. If SIGPIPE is ignored (which both Python and Rust do by default),
the write fails and surfaces as a traceback or panic on stderr plus a wrong exit code. Check
every CLI for this; the fix is language-specific (§8). The symptom differs: Python prints a
BrokenPipeError traceback and exits 1; Rust prints a panic and exits 101, which is
indistinguishable from a genuine bug — a Rust CLI reporting 101 in a bug report should make you
suspect this first.
- Exit codes must distinguish failure classes, and no two classes may collide. The reviewable
property is consistency and documentation, not which scheme. A CLI that returns 2 for both
"you typed it wrong" (the parser's convention) and "this build doesn't do that" has made those
indistinguishable to a caller. Do not prescribe
sysexits.h — see the contested list.
- Zero on failure is a defect unless it is a documented inversion. A hook or shim that must
never break its host can legitimately always exit 0, provided failures are routed to a channel
the user can actually see (a health log with a
doctor command, say). Check that the
compensating channel exists before calling it a bug — and check it exists before calling it fine.
- Signal handling. If the tool catches SIGINT for cleanup, it should still terminate promptly
and bound the cleanup; a second Ctrl-C must escape. Exiting 130 imitates what the shell reports
for an uncaught SIGINT (128+2) and is the usual convention, though no primary source states it
directly.
- A signal-terminated child's status is not an exit code. Passing a negative or raw wait status
straight to the process exit turns Ctrl-C in a child into a nonsense shell status.
2. Streams & machine-readable output
- Primary output and anything machine-readable on stdout; every log, error and progress message
on stderr. The tell is a diagnostic on stdout right next to a mechanism that gets it right —
a prompt preamble printed to stdout while the prompt itself goes to stderr, or a line saying
"see the warning above" when the warning went to stderr and the user redirected stdout to a file.
- Help is not an error. Requested help → stdout, exit 0. Usage error → stderr, non-zero. A tool
that prints
--help to stderr is wrong, and so is one that prints a usage error to stdout. This
one has a definite answer; see the contested list for why the folklore says otherwise.
- A machine-readable format is what earns the freedom to change human output. A tool with no
--json/--plain has implicitly made its pretty output an API. Check that machine output
carries a schema version the consumer can branch on, and that nothing else is interleaved on
stdout when it is active.
- Column widths computed from the result set are fine for humans and a trap for scripts — a
note rather than a defect when a stable format is offered alongside.
- Colour off when not a TTY, and when
NO_COLOR is set and non-empty regardless of its value.
Check stdout and stderr independently: piping stdout does not mean stderr colour is unwanted.
If the tool emits no colour at all, this whole item is moot — don't invent it.
3. Interactivity, TTY & destructive actions
- The gate must exist on every path that reaches the command. The highest-value check in this
skill. When a destructive command has no confirmation because something else makes it
recoverable — an undo, a trash, a backup — verify that thing is available on every backend,
platform and configuration the command runs under. A safety net that exists for one of two
storage backends does not gate the command; it gates half of it.
- Non-TTY must refuse, not assume. Silence is not consent and EOF is not yes. The correct
shape is: explicit
--yes/--force → proceed; interactive terminal → prompt; otherwise →
refuse with a message naming the flag that would have worked. Checking that both stdin and
stderr are terminals is stricter than the common stdin-only check and is right.
- Never require a prompt. Every prompted value needs a flag or argument equivalent, or the
command is unscriptable. Prompts also belong at the CLI edge, not in the library layer where
every caller — tests included — has to arrange a TTY.
- Unguarded
input()/read crashes under < /dev/null and in CI. Check every prompt, not the
first one; these are usually copy-pasted, and the guard is usually on some of the copies.
- Match the gate to the blast radius. Deleting one named thing the user just named may need no
prompt. A bulk or remote deletion needs one. Something irreversible and large should be hard to
confirm by accident — requiring the name to be typed, with a flag form like
--confirm=<name> so it stays scriptable, is the design that satisfies both.
- Watch for non-obvious destruction — a config value changed from 10 to 1 that implicitly
deletes nine things is a severe action wearing an edit's clothing.
4. Dry-run, partial failure & idempotency
- A dry-run flag must be threaded to the lowest write primitive, not checked at the command
handler. An
if not dry_run: at each call site is a promise a future caller will forget.
In a typed language, ask for the stronger form: pass an effect enum or a writer into the
backend so a path that writes without consulting it fails to compile.
- If it dies halfway, what is on disk, and is a re-run safe? Trace a mid-loop failure
explicitly. Idempotent-by-accident (the re-run happens to work) is worth crediting and worth
naming as accidental — the reviewer's question is whether the recovery path was designed or
merely available today.
- Batch commands: validate everything, then apply everything. Resolving all inputs before the
first mutation is the pattern; the alternative needs a documented partial-result contract and
an exit code that expresses it. There is no established convention for what a bulk command
should exit when 7 of 10 items succeed — so the finding is that the tool must decide and
document it, not that it picked wrong.
- Never report an action that did not happen. Idempotency at the library layer is correct;
narrating it as though it occurred is the bug. "removed X" with exit 0 when X was never present
is a defect in any language — and it is worse when a typo'd argument triggers a teardown path
that then reports success.
- Atomic writes and durability — temp file in the same directory, then rename. Whether the
contents are
fsynced before the rename decides whether a power cut yields a truncated file.
Check especially where the tool rewrites files it does not own.
- Cap unbounded stdin if the tool reads it.
- Parse arguments before loading config, so
--help still works on a machine with a broken
config file. Easy to get backwards, trivial to check.
5. Config precedence
Per-change: a new setting must join the existing precedence chain, not start a second one. If
the diff reads an environment variable or a config key directly instead of going through the
project's one resolution function, that is the finding — a second copy of the order is how
precedence drifts. Whether the order itself is right, and whether config lands in the correct XDG
root, is §P.
Also per-change: a new secret read from a flag (it leaks into ps and shell history) or from an
environment variable. A --password-file or stdin is the shape.
6. Flags & subcommands
Per-change, all of these are about the new surface agreeing with the surface it joins:
- A new flag or subcommand inconsistent with its siblings — the same concept spelled
differently, a short alias where siblings have none,
--json on three subcommands and not the
fourth. A consistency promise already made is a defect to break; one never made is a scope
decision.
- A new flag whose help text is missing while its siblings have one.
- A required thing modeled as optional — a flag declared optional but handled only in its
present form, producing a confusing fallthrough instead of the parser's "required argument not
provided". Let the parser express the constraint.
- A new conflict hand-checked instead of declared to the parser, so it neither appears in help
nor fails uniformly.
- Validation for the new flag living in a second layer — the same mistake reachable two ways
should produce the same message and the same exit code and envelope. A shared validator reached
through two layers often doesn't.
- A changed flag, output shape, or subcommand name. These are interfaces you have committed to;
a rename breaks scripts in the wild. Watch for a new catch-all subcommand or newly-allowed
abbreviation, both of which make it impossible to add names later.
7. Errors & messages
- An error should name the next action. "unknown project
nope — configured project(s): demo"
is a finding-free error. A bare string with no remedy is the defect. The fuller shape worth
aiming at: what failed, why, and how to fix it, plus a code or URL when there is one.
- Don't lose the cause at a boundary. Stringifying an I/O error into a message discards the
path, the operation and the error kind, so no caller can branch on not-found versus
permission-denied and the user sees "No such file or directory" with no indication which file.
This costs more in languages where the chain is not printed for free (§8).
- A pointer to a message on another stream is not a message. See §2.
- The worst message is a success message for something that did not happen. See §4.
P. Project-level checks — --all only
These are decided once and almost never regress. Run them on a full audit; never report them on a
diff review, where they are noise that buries the real findings.
The full probe table:
| Probe |
Expected |
cmd --help; echo $? |
Help on stdout, exit 0. GNU: "output brief documentation for how to invoke the program, on standard output, then exit successfully." |
cmd --bogus >/dev/null; echo $? |
Usage error on stderr, non-zero (2 by convention) |
cmd --version; echo $? |
Prints a version, exit 0 — a version subcommand alone fails every script and packaging tool that probes for the flag |
cmd <long output> | head -1 |
No traceback, no panic, empty stderr |
cmd | cat -v | grep -c $'\e\[' |
0 — colour off when not a TTY |
NO_COLOR=1 cmd | cat -v | grep -c $'\e\[' |
0 |
cmd --json | jq . |
Valid JSON, nothing else on stdout |
cmd -- -weirdname |
-- terminates option parsing (POSIX Guideline 10) |
echo x | cmd - |
- means stdin (POSIX Guideline 13) |
| Ctrl-C during a long run |
Exits promptly; a second Ctrl-C escapes cleanup |
Plus, read once:
- Does
--help carry what the README carries? A CLI whose subcommands have no descriptions
while the README documents all of them has put its documentation where the user isn't.
- Is SIGPIPE handled at all, anywhere — one fix in
main covers every write site (§8).
- Is precedence implemented exactly once, in one function every consumer calls, including any
which/debug command that reports the resolution?
- Are config, data, state and cache in the right XDG roots? The one people get wrong is state:
per the spec,
$XDG_STATE_HOME holds data that persists between restarts but is "not important or
portable enough to the user that it should be stored in $XDG_DATA_HOME" — history, logs,
last-used selections. Credentials and user-authored content are data. The test: would the user
want this back on a new machine?
- Does a machine-readable format exist, and does it declare a schema version a consumer can
branch on? A tool with none has implicitly made its pretty output an API.
- Is there a
--dry-run where the destructive surface warrants one?
8. What differs by language
The checks above are identical everywhere. These fixes are not — load
references/language-notes.md before writing one. The three that most often change the finding
itself:
| Concern |
Python |
Rust |
| Broken pipe |
Catch BrokenPipeError, dup2 stdout to devnull, exit 1. The Python docs explicitly advise against signal.signal(SIGPIPE, SIG_DFL) |
No stable language-level fix. #[unix_sigpipe] no longer exists as a feature name; -Zon-broken-pipe is nightly-only. Either libc::signal(SIGPIPE, SIG_DFL) in an unsafe block first thing in main, or match ErrorKind::BrokenPipe on a locked buffered writer |
| Exit mechanism |
sys.exit(n); a signal-killed child's negative status must be normalized before it becomes the exit code |
Three mechanisms with different semantics. Returning Result from main prints the Debug form and exits 1 — a real UX defect. process::exit skips destructors, weakening any lock guard or temp-file cleanup. ExitCode is the right default |
| Error chaining |
raise X from e; the interpreter prints the chain |
Nothing prints the source chain automatically, so one-level Display drops it. Stringifying an I/O error also discards the path and ErrorKind — a much more expensive mistake than in Python |
The reference also covers stream discipline (Rust can turn this into a compile gate; Python can't),
dry-run enforcement, atomic writes, env precedence, and file locking.
Do NOT flag these
- Anything in §P, on a diff review. Missing
--version, thin --help, XDG placement and
precedence structure are project properties; they have not changed because this diff didn't touch
them, and reporting them every time trains the reader to skim.
- Missing
--json on a tool with no machine consumers, or NO_COLOR handling on a tool that
emits no colour. Both are real rules with a precondition; check the precondition.
- Deviations from POSIX Utility Syntax Guidelines 3, 7 and 9. Guideline 3 permits only
single-character options, so
--long has no POSIX basis at all; 7 forbids optional
option-arguments; 9 requires options before operands. Git, docker and cargo all violate these
deliberately. Guidelines 4, 10 and 13 are the durable ones.
- Not adopting
sysexits.h — deprecated by the BSD that originated it, documented neutrally
by Linux, still recommended by the Rust CLI Book. No consensus; don't manufacture one.
- Prescribing a specific exit number beyond 0/non-zero and the 2-for-usage convention.
- A deliberate always-exit-0 inversion with a working diagnostic channel (§1).
- Idempotent library behaviour — the bug is narrating it as an action, not the idempotency.
- Anything the project's own enabled lints already gate, including a Rust crate that has
turned on the print lints.
Output Format
## CLI Review: {scope}
### Baseline
{Probes you ran and what happened, including any you could not run and why. Language and argument
library. **At `--all` only:** the §P results. On a diff review, omit this block unless a probe you
ran actually failed.}
### Critical Issues (Must Fix)
- {file}:{line} — {category}: {description}
**Probe:** {the command and its actual output, where a probe found it}
**Impact:** {what breaks, for whom}
**Fix:** {concrete change — with code, in this project's language}
### Improvements (Should Fix)
- {file}:{line} — {category}: {description}
**Fix:** {solution}
### Suggestions (Nice to Have)
- {file}:{line} — {category}: {description} — {suggested change}
If --multi was used, append one subsection per advisor that responded (titled with the advisor's
name as reported by second-opinion), then a Cross-Model Agreement subsection.
Examples
A gate that only covers half the paths:
/review-cli --all
rm has no confirmation, no --yes and no --force. The justification is an undo command — but
undo is only wired for one of two storage backends, and on the other it returns "this backend
does not support undo". Reports Must Fix: on that backend rm is unprompted and unrecoverable.
The finding needs reading the gate, the thing that justifies its absence, and every construction
path of that thing — three places, none of which look wrong alone.
Broken pipe, found by probe not by reading:
/review-cli
cmd ls | head -3 prints three rows and then panics — failed printing to stdout: Broken pipe,
exit 101. Nothing in the source mentions SIGPIPE, and nothing looks wrong: it is a plain print in
a loop. Reports Should Fix with the one-line fix for the language, and notes that exit 101 will be
misread as a genuine bug in any report.
Success message for a no-op:
/review-cli --changed
uninstall --consumer <typo> removes nothing, then reports "removed consumer (last
consumer; hooks and active binary removed)" and exits 0 — having actually torn down the shared
hooks, because zero registered consumers remain. The idempotent remove is correct; the message is
the defect. Reports Must Fix: a misspelled argument performs a full teardown and reports success.
Troubleshooting
Can't build or install the tool, so Step 0 is impossible
Solution: Review §2–§7 from the source and say in the Baseline that probes were not run. Do
not infer probe results from reading — the whole point of Step 0 is that these behaviours don't
appear in the source. Ask the user for a build command or a fixture project rather than guessing.
The pipe probe passes but the tool looks unprotected
Solution: The output fit in the pipe buffer (~64 KB), so the writer never saw the closed pipe.
Re-run against the largest output the tool can produce, or a project with real data in it. A tool
can be exposed by construction and shielded only by volume — that is still a finding, because the
volume is the user's data, not a property of the tool.
Unsure whether a missing affordance is a defect or a scope decision
Solution: Check whether the tool's own conventions imply it. A CLI that offers --json on
three subcommands and not the fourth has made a consistency promise; one that offers it nowhere
has made a scope decision. Same for --dry-run, short flags, and confirmation prompts. Report the
first as a defect and the second as a suggestion, if at all.
Notes
- Probe first, read second. The probes cost a minute and find the defects that reading misses.
- Respect project conventions in AGENTS.md / CLAUDE.md, and read the README — a gap between it and
--help is a finding in its own right.
- Don't be dogmatic. The most-cited source in this area says of itself: "When following convention
would compromise a program's usability, it might be time to break with it—but such a decision
should be made with care." Look for the decision, not just the deviation.
- Credit what's right. A CLI that refuses on a non-TTY with a message naming both escapes, or that
re-parses its own rendering before writing a file it doesn't own, is doing something most don't —
and saying so keeps the review honest about what the remaining findings cost.
- Sources: Command Line Interface Guidelines (clig.dev); POSIX Utility Syntax Guidelines and
<signal.h>; the GNU Coding Standards on --help and --version; the XDG Base Directory
Specification; no-color.org; the GNU Bash manual on exit status; the Python signal docs' note
on SIGPIPE; the Rust CLI Book and the -Zon-broken-pipe documentation; 12 Factor CLI Apps; git's
--porcelain stability wording. Quoted lines and the contested list are in
references/conventions.md.
1---2name: review-cli3description: Language-agnostic review of a command-line tool's interface and behaviour — exit codes and signals, broken-pipe handling, stdout/stderr discipline, TTY detection and destructive-action gating, dry-run integrity, partial failure and idempotency, config precedence, flag and help design, and error messages that name the next action. Starts by RUNNING the binary, because most of this is invisible in the source. Applies equally to Python, Rust, Go, Node and shell-invoked tools. Auto-invoked by `code-review` on projects that ship a console entry point. Triggers "review cli", "cli review", "command line interface review", "review the CLI UX".4argument-hint: '[--staged | --unpushed | --changed | --all | --multi]'5effort: high6metadata:7 source: https://skillmd.com/skills/nielsmadan/review-cli8---910<!-- Generated from https://github.com/nielsmadan/agentic-coding — edits here are overwritten. -->1112# Review CLI1314Review of the interface a command-line tool *presents*, not the language it is written in. The15checks below are the same for a Python CLI and a Rust one; only the fixes differ, and §8 carries16those.1718Complements `review-<language>` skills (which review the code) and `review-interfaces` (which19reviews function and module signatures, not the CLI surface). Don't repeat either.2021## Review grading2223Use only these finding priorities, in descending order:2425- **Critical Issues (Must Fix):** a verified path causes data loss, a security failure, a materially26 wrong operation, or makes a core workflow unusable without reasonable recovery.27- **Improvements (Should Fix):** an ordinary supported workflow demonstrably fails or repeatedly28 imposes substantial friction, or a concrete design defect creates meaningful maintenance cost.29- **Suggestions (Nice to Have):** a worthwhile improvement with small practical impact, including30 optional polish, local simplification, and rare recoverable edge cases.3132Grade the demonstrated consequence, realistic reachability, and available recovery against project33priorities. A category, missing convention, hypothetical future problem, or confidence that a claim34is true does not set its priority. Do not assign automatic severity floors or ceilings. Keep35unverified claims in validation gaps, outside the graded finding count; distinguish suggestions36from defects. For plans, trace the consequence if implemented and state the assumptions.3738Use the short labels **Must Fix**, **Should Fix**, and **Nice to Have** in summaries and ledgers.39Keep effort, verification status, user-facing change size, and tool/vendor diagnostic ratings40separate. When called by `code-review`, return its requested evidence and impact fields; the parent41owns scoring and final triage. Otherwise apply this rubric directly. Omit empty priority sections.4243## Relationship to the toolchain (read first)4445**There is essentially no tooling for this layer.** That is not an assumption — a search across46four phrasings for a CLI-design linter turned up clig.dev itself, generic static-analysis47round-ups, and no tool. ShellCheck analyses *shell scripts*, i.e. programs written in bash; it says48nothing about the interface a compiled or Python program presents. Neither ruff nor clippy ships a49CLI-conventions rule set.5051Two narrow exceptions worth knowing:5253- **Rust can mechanize the stream discipline** in §2. `clippy::print_stdout` and54 `clippy::print_stderr` are restriction lints — off by default, but a crate can turn them on and55 `#[allow]` the handful of genuine output sites. When reviewing a Rust CLI, *recommend enabling56 the lint* rather than listing instances one by one.57- **`clap::Command::debug_assert()`** catches duplicate short flags and conflicting requirements —58 definition consistency, not design.5960So this skill carries more weight than a language review does, and **its findings must be earned61by evidence**, since nothing else will catch a mistake here and nothing else will catch a false62positive either.6364## What this skill checks6566**A CLI's design is decided once; its behaviour regresses continuously.** So the default review67looks only at what the diff introduces — a new subcommand, a new output path, a new destructive68operation, a new prompt. One-time properties (does `--version` exist, does `--help` carry69descriptions, are config roots XDG-correct) belong to the **project-level set in §P**, which runs70at `--all` and nowhere else. Re-checking those on every diff is noise, and it buries the findings71that matter.7273## Step 0: probe what the diff touches7475Most CLI behaviour is invisible in the source, so run the thing rather than reading it — but scope76the probing to the change:7778- **Any scope:** if the diff adds or changes an output path, pipe it into `head` and check stderr79 is empty. If it adds a destructive operation, run it with `< /dev/null`. If it adds `--json`80 output, pipe it through `jq`.81- **`--all` only:** the full probe table in §P.8283**The pipe probe needs output larger than the pipe buffer (~64 KB)** or it silently passes. Use the84largest output the changed command can produce.8586A probe you could not run (no build, no fixture data) is reported as *not run*, never as passing.8788## Usage8990```91/review-cli # Review context-related code92/review-cli --staged # Review staged changes93/review-cli --unpushed # Review files changed across all unpushed commits94/review-cli --changed # Review unstaged changes95/review-cli --all # Full CLI surface audit (the natural scope for this skill)96/review-cli --multi # Also get external advisor opinions97```9899## Scope100101| Flag | Scope | Method |102|------|-------|--------|103| (none) | Context-related code | Files from the current conversation context, plus the CLI entry point and argument definitions regardless of scope — a diff to one subcommand is reviewed against the whole interface it joins. |104| `--staged` | Staged changes | `git diff --cached --name-only` |105| `--unpushed` | Files changed across unpushed commits | `git diff --name-only $(git rev-list HEAD --not --remotes \| tail -1)^..HEAD` |106| `--changed` | Unstaged changes | `git diff --name-only` |107| `--all` | Whole CLI surface + **§P project-level checks** | Entry point, argument definitions, every subcommand handler, output and prompt helpers |108| `--multi` | Add external opinions | Combines with any scope above; invokes `second-opinion --quick` |109110**Only `--all` runs §P.** At every other scope the review covers §1–§8 against what the diff111introduces, and a §P finding is out of scope even if you notice it — note it in one line at the end112if it is severe, but never as a review finding.113114## Workflow1151161. **Determine scope** and locate the entry point and argument definitions.1172. **Run the Step 0 probes.** Record results.1183. **Read AGENTS.md / CLAUDE.md / README** — the README matters unusually much here, because a119 gap between what it documents and what `--help` says is itself a finding (§6).1204. **Review against §1–§7.** Load `references/conventions.md` for the normative sources and the121 contested list; load `references/language-notes.md` when writing a fix.1225. **Parallelize** if the CLI has many subcommands: one sub-agent per category, merge and dedupe.1236. **External opinions** (if `--multi`): invoke `second-opinion --quick` with this prompt:124125 ```126 Read-only review of a command-line tool's interface, not its implementation language. No127 linter covers this layer, so nothing is out of scope for being mechanical. Focus on: does a128 destructive command have a gate, and is whatever justifies skipping it available on every code129 path that reaches it? Does the tool refuse rather than assume when stdin is not a terminal?130 Does it ever report an action that did not happen? Do exit codes distinguish failure classes131 without colliding? Is primary output on stdout and every diagnostic on stderr? Does a dry-run132 flag reach the lowest write primitive or just the command handler? If it dies halfway, what is133 left behind and is a re-run safe? Do errors say what to do next? 300 words or less.134 ```135136 Wait for all external results before proceeding.1377. **Classify severity** and **report**, grouped by severity.138139## 1. Exit codes & signals140141- **Broken pipe is the single most commonly missed defect.** A tool piped into `head` keeps142 writing after the reader exits. If SIGPIPE is ignored (which both Python and Rust do by default),143 the write fails and surfaces as a traceback or panic on stderr plus a wrong exit code. **Check144 every CLI for this**; the fix is language-specific (§8). The symptom differs: Python prints a145 `BrokenPipeError` traceback and exits 1; Rust prints a *panic* and exits **101**, which is146 indistinguishable from a genuine bug — a Rust CLI reporting 101 in a bug report should make you147 suspect this first.148- **Exit codes must distinguish failure classes, and no two classes may collide.** The reviewable149 property is consistency and documentation, not which scheme. A CLI that returns 2 for both150 "you typed it wrong" (the parser's convention) and "this build doesn't do that" has made those151 indistinguishable to a caller. Do **not** prescribe `sysexits.h` — see the contested list.152- **Zero on failure is a defect unless it is a documented inversion.** A hook or shim that must153 never break its host can legitimately always exit 0, provided failures are routed to a channel154 the user can actually see (a health log with a `doctor` command, say). Check that the155 compensating channel exists before calling it a bug — and check it exists before calling it fine.156- **Signal handling.** If the tool catches SIGINT for cleanup, it should still terminate promptly157 and bound the cleanup; a second Ctrl-C must escape. Exiting 130 imitates what the shell reports158 for an uncaught SIGINT (128+2) and is the usual convention, though no primary source states it159 directly.160- **A signal-terminated child's status is not an exit code.** Passing a negative or raw wait status161 straight to the process exit turns Ctrl-C in a child into a nonsense shell status.162163## 2. Streams & machine-readable output164165- **Primary output and anything machine-readable on stdout; every log, error and progress message166 on stderr.** The tell is a *diagnostic on stdout right next to a mechanism that gets it right* —167 a prompt preamble printed to stdout while the prompt itself goes to stderr, or a line saying168 "see the warning above" when the warning went to stderr and the user redirected stdout to a file.169- **Help is not an error.** Requested help → stdout, exit 0. Usage error → stderr, non-zero. A tool170 that prints `--help` to stderr is wrong, and so is one that prints a usage error to stdout. This171 one has a definite answer; see the contested list for why the folklore says otherwise.172- **A machine-readable format is what earns the freedom to change human output.** A tool with no173 `--json`/`--plain` has implicitly made its pretty output an API. Check that machine output174 carries a **schema version** the consumer can branch on, and that nothing else is interleaved on175 stdout when it is active.176- **Column widths computed from the result set** are fine for humans and a trap for scripts — a177 note rather than a defect when a stable format is offered alongside.178- **Colour off when not a TTY, and when `NO_COLOR` is set and non-empty** regardless of its value.179 Check stdout and stderr independently: piping stdout does not mean stderr colour is unwanted.180 If the tool emits no colour at all, this whole item is moot — don't invent it.181182## 3. Interactivity, TTY & destructive actions183184- **The gate must exist on every path that reaches the command.** The highest-value check in this185 skill. When a destructive command has no confirmation because something else makes it186 recoverable — an undo, a trash, a backup — verify that thing is available on *every* backend,187 platform and configuration the command runs under. A safety net that exists for one of two188 storage backends does not gate the command; it gates half of it.189- **Non-TTY must refuse, not assume.** Silence is not consent and EOF is not yes. The correct190 shape is: explicit `--yes`/`--force` → proceed; interactive terminal → prompt; otherwise →191 refuse with a message naming the flag that would have worked. Checking that *both* stdin and192 stderr are terminals is stricter than the common stdin-only check and is right.193- **Never require a prompt.** Every prompted value needs a flag or argument equivalent, or the194 command is unscriptable. Prompts also belong at the CLI edge, not in the library layer where195 every caller — tests included — has to arrange a TTY.196- **Unguarded `input()`/read crashes under `< /dev/null` and in CI.** Check every prompt, not the197 first one; these are usually copy-pasted, and the guard is usually on some of the copies.198- **Match the gate to the blast radius.** Deleting one named thing the user just named may need no199 prompt. A bulk or remote deletion needs one. Something irreversible and large should be hard to200 confirm *by accident* — requiring the name to be typed, with a flag form like201 `--confirm=<name>` so it stays scriptable, is the design that satisfies both.202- **Watch for non-obvious destruction** — a config value changed from 10 to 1 that implicitly203 deletes nine things is a severe action wearing an edit's clothing.204205## 4. Dry-run, partial failure & idempotency206207- **A dry-run flag must be threaded to the lowest write primitive, not checked at the command208 handler.** An `if not dry_run:` at each call site is a promise a future caller will forget.209 In a typed language, ask for the stronger form: pass an effect enum or a writer into the210 backend so a path that writes without consulting it fails to compile.211- **If it dies halfway, what is on disk, and is a re-run safe?** Trace a mid-loop failure212 explicitly. Idempotent-by-accident (the re-run happens to work) is worth crediting and worth213 naming as accidental — the reviewer's question is whether the recovery path was designed or214 merely available today.215- **Batch commands: validate everything, then apply everything.** Resolving all inputs before the216 first mutation is the pattern; the alternative needs a documented partial-result contract and217 an exit code that expresses it. There is no established convention for what a bulk command218 should exit when 7 of 10 items succeed — so the finding is that the tool must *decide and219 document* it, not that it picked wrong.220- **Never report an action that did not happen.** Idempotency at the library layer is correct;221 narrating it as though it occurred is the bug. "removed X" with exit 0 when X was never present222 is a defect in any language — and it is worse when a typo'd argument triggers a teardown path223 that then reports success.224- **Atomic writes and durability** — temp file in the same directory, then rename. Whether the225 contents are `fsync`ed before the rename decides whether a power cut yields a truncated file.226 Check especially where the tool rewrites files it does not own.227- **Cap unbounded stdin** if the tool reads it.228- **Parse arguments before loading config**, so `--help` still works on a machine with a broken229 config file. Easy to get backwards, trivial to check.230231## 5. Config precedence232233Per-change: **a new setting must join the existing precedence chain, not start a second one.** If234the diff reads an environment variable or a config key directly instead of going through the235project's one resolution function, that is the finding — a second copy of the order is how236precedence drifts. Whether the order itself is right, and whether config lands in the correct XDG237root, is §P.238239Also per-change: a new secret read from a flag (it leaks into `ps` and shell history) or from an240environment variable. A `--password-file` or stdin is the shape.241242## 6. Flags & subcommands243244Per-change, all of these are about the **new** surface agreeing with the surface it joins:245246- **A new flag or subcommand inconsistent with its siblings** — the same concept spelled247 differently, a short alias where siblings have none, `--json` on three subcommands and not the248 fourth. A consistency promise already made is a defect to break; one never made is a scope249 decision.250- **A new flag whose help text is missing** while its siblings have one.251- **A required thing modeled as optional** — a flag declared optional but handled only in its252 present form, producing a confusing fallthrough instead of the parser's "required argument not253 provided". Let the parser express the constraint.254- **A new conflict hand-checked** instead of declared to the parser, so it neither appears in help255 nor fails uniformly.256- **Validation for the new flag living in a second layer** — the same mistake reachable two ways257 should produce the same message *and* the same exit code and envelope. A shared validator reached258 through two layers often doesn't.259- **A changed flag, output shape, or subcommand name.** These are interfaces you have committed to;260 a rename breaks scripts in the wild. Watch for a new catch-all subcommand or newly-allowed261 abbreviation, both of which make it impossible to add names later.262263## 7. Errors & messages264265- **An error should name the next action.** "unknown project `nope` — configured project(s): demo"266 is a finding-free error. A bare string with no remedy is the defect. The fuller shape worth267 aiming at: what failed, why, and how to fix it, plus a code or URL when there is one.268- **Don't lose the cause at a boundary.** Stringifying an I/O error into a message discards the269 path, the operation and the error kind, so no caller can branch on not-found versus270 permission-denied and the user sees "No such file or directory" with no indication which file.271 This costs more in languages where the chain is not printed for free (§8).272- **A pointer to a message on another stream is not a message.** See §2.273- **The worst message is a success message for something that did not happen.** See §4.274275## P. Project-level checks — `--all` only276277These are decided once and almost never regress. Run them on a full audit; **never report them on a278diff review**, where they are noise that buries the real findings.279280**The full probe table:**281282| Probe | Expected |283|---|---|284| `cmd --help; echo $?` | Help on **stdout**, exit **0**. GNU: "output brief documentation for how to invoke the program, on standard output, then exit successfully." |285| `cmd --bogus >/dev/null; echo $?` | Usage error on **stderr**, non-zero (2 by convention) |286| `cmd --version; echo $?` | Prints a version, exit 0 — a `version` *subcommand* alone fails every script and packaging tool that probes for the flag |287| `cmd <long output> \| head -1` | No traceback, no panic, empty stderr |288| `cmd \| cat -v \| grep -c $'\e\['` | 0 — colour off when not a TTY |289| `NO_COLOR=1 cmd \| cat -v \| grep -c $'\e\['` | 0 |290| `cmd --json \| jq .` | Valid JSON, nothing else on stdout |291| `cmd -- -weirdname` | `--` terminates option parsing (POSIX Guideline 10) |292| `echo x \| cmd -` | `-` means stdin (POSIX Guideline 13) |293| Ctrl-C during a long run | Exits promptly; a second Ctrl-C escapes cleanup |294295**Plus, read once:**296297- **Does `--help` carry what the README carries?** A CLI whose subcommands have no descriptions298 while the README documents all of them has put its documentation where the user isn't.299- **Is SIGPIPE handled at all**, anywhere — one fix in `main` covers every write site (§8).300- **Is precedence implemented exactly once**, in one function every consumer calls, including any301 `which`/`debug` command that reports the resolution?302- **Are config, data, state and cache in the right XDG roots?** The one people get wrong is state:303 per the spec, `$XDG_STATE_HOME` holds data that persists between restarts but is "not important or304 portable enough to the user that it should be stored in `$XDG_DATA_HOME`" — history, logs,305 last-used selections. Credentials and user-authored content are data. The test: *would the user306 want this back on a new machine?*307- **Does a machine-readable format exist, and does it declare a schema version** a consumer can308 branch on? A tool with none has implicitly made its pretty output an API.309- **Is there a `--dry-run` where the destructive surface warrants one?**310311## 8. What differs by language312313The checks above are identical everywhere. These fixes are not — **load314`references/language-notes.md` before writing one.** The three that most often change the finding315itself:316317| Concern | Python | Rust |318|---|---|---|319| **Broken pipe** | Catch `BrokenPipeError`, `dup2` stdout to devnull, exit 1. The Python docs explicitly advise **against** `signal.signal(SIGPIPE, SIG_DFL)` | **No stable language-level fix.** `#[unix_sigpipe]` no longer exists as a feature name; `-Zon-broken-pipe` is nightly-only. Either `libc::signal(SIGPIPE, SIG_DFL)` in an `unsafe` block first thing in `main`, or match `ErrorKind::BrokenPipe` on a locked buffered writer |320| **Exit mechanism** | `sys.exit(n)`; a signal-killed child's negative status must be normalized before it becomes the exit code | Three mechanisms with different semantics. Returning `Result` from `main` prints the **Debug** form and exits 1 — a real UX defect. `process::exit` skips destructors, weakening any lock guard or temp-file cleanup. `ExitCode` is the right default |321| **Error chaining** | `raise X from e`; the interpreter prints the chain | Nothing prints the source chain automatically, so one-level `Display` drops it. Stringifying an I/O error also discards the path and `ErrorKind` — a much more expensive mistake than in Python |322323The reference also covers stream discipline (Rust can turn this into a compile gate; Python can't),324dry-run enforcement, atomic writes, env precedence, and file locking.325326## Do NOT flag these327328- **Anything in §P, on a diff review.** Missing `--version`, thin `--help`, XDG placement and329 precedence structure are project properties; they have not changed because this diff didn't touch330 them, and reporting them every time trains the reader to skim.331- **Missing `--json` on a tool with no machine consumers**, or `NO_COLOR` handling on a tool that332 emits no colour. Both are real rules with a precondition; check the precondition.333- **Deviations from POSIX Utility Syntax Guidelines 3, 7 and 9.** Guideline 3 permits only334 single-character options, so `--long` has no POSIX basis at all; 7 forbids optional335 option-arguments; 9 requires options before operands. Git, docker and cargo all violate these336 deliberately. Guidelines 4, 10 and 13 are the durable ones.337- **Not adopting `sysexits.h`** — deprecated by the BSD that originated it, documented neutrally338 by Linux, still recommended by the Rust CLI Book. No consensus; don't manufacture one.339- **Prescribing a specific exit number** beyond 0/non-zero and the 2-for-usage convention.340- **A deliberate always-exit-0 inversion** with a working diagnostic channel (§1).341- **Idempotent library behaviour** — the bug is narrating it as an action, not the idempotency.342- **Anything the project's own enabled lints already gate**, including a Rust crate that has343 turned on the print lints.344345346## Output Format347348```markdown349## CLI Review: {scope}350351### Baseline352{Probes you ran and what happened, including any you could not run and why. Language and argument353library. **At `--all` only:** the §P results. On a diff review, omit this block unless a probe you354ran actually failed.}355356### Critical Issues (Must Fix)357- {file}:{line} — {category}: {description}358 **Probe:** {the command and its actual output, where a probe found it}359 **Impact:** {what breaks, for whom}360 **Fix:** {concrete change — with code, in this project's language}361362### Improvements (Should Fix)363- {file}:{line} — {category}: {description}364 **Fix:** {solution}365366### Suggestions (Nice to Have)367- {file}:{line} — {category}: {description} — {suggested change}368369```370371If `--multi` was used, append one subsection per advisor that responded (titled with the advisor's372name as reported by `second-opinion`), then a **Cross-Model Agreement** subsection.373374## Examples375376**A gate that only covers half the paths:**377> /review-cli --all378379`rm` has no confirmation, no `--yes` and no `--force`. The justification is an `undo` command — but380`undo` is only wired for one of two storage backends, and on the other it returns "this backend381does not support undo". Reports Must Fix: on that backend `rm` is unprompted and unrecoverable.382The finding needs reading the gate, the thing that justifies its absence, and every construction383path of that thing — three places, none of which look wrong alone.384385**Broken pipe, found by probe not by reading:**386> /review-cli387388`cmd ls | head -3` prints three rows and then panics — `failed printing to stdout: Broken pipe`,389exit 101. Nothing in the source mentions SIGPIPE, and nothing looks wrong: it is a plain print in390a loop. Reports Should Fix with the one-line fix for the language, and notes that exit 101 will be391misread as a genuine bug in any report.392393**Success message for a no-op:**394> /review-cli --changed395396`uninstall --consumer <typo>` removes nothing, then reports "removed consumer <typo> (last397consumer; hooks and active binary removed)" and exits 0 — having actually torn down the shared398hooks, because zero registered consumers remain. The idempotent remove is correct; the message is399the defect. Reports Must Fix: a misspelled argument performs a full teardown and reports success.400401## Troubleshooting402403### Can't build or install the tool, so Step 0 is impossible404**Solution:** Review §2–§7 from the source and say in the Baseline that probes were not run. Do405not infer probe results from reading — the whole point of Step 0 is that these behaviours don't406appear in the source. Ask the user for a build command or a fixture project rather than guessing.407408### The pipe probe passes but the tool looks unprotected409**Solution:** The output fit in the pipe buffer (~64 KB), so the writer never saw the closed pipe.410Re-run against the largest output the tool can produce, or a project with real data in it. A tool411can be exposed by construction and shielded only by volume — that is still a finding, because the412volume is the user's data, not a property of the tool.413414### Unsure whether a missing affordance is a defect or a scope decision415**Solution:** Check whether the tool's own conventions imply it. A CLI that offers `--json` on416three subcommands and not the fourth has made a consistency promise; one that offers it nowhere417has made a scope decision. Same for `--dry-run`, short flags, and confirmation prompts. Report the418first as a defect and the second as a suggestion, if at all.419420## Notes421422- Probe first, read second. The probes cost a minute and find the defects that reading misses.423- Respect project conventions in AGENTS.md / CLAUDE.md, and read the README — a gap between it and424 `--help` is a finding in its own right.425- Don't be dogmatic. The most-cited source in this area says of itself: "When following convention426 would compromise a program's usability, it might be time to break with it—but such a decision427 should be made with care." Look for the decision, not just the deviation.428- Credit what's right. A CLI that refuses on a non-TTY with a message naming both escapes, or that429 re-parses its own rendering before writing a file it doesn't own, is doing something most don't —430 and saying so keeps the review honest about what the remaining findings cost.431- Sources: Command Line Interface Guidelines (clig.dev); POSIX Utility Syntax Guidelines and432 `<signal.h>`; the GNU Coding Standards on `--help` and `--version`; the XDG Base Directory433 Specification; no-color.org; the GNU Bash manual on exit status; the Python `signal` docs' note434 on SIGPIPE; the Rust CLI Book and the `-Zon-broken-pipe` documentation; 12 Factor CLI Apps; git's435 `--porcelain` stability wording. Quoted lines and the contested list are in436 `references/conventions.md`.