Rust CLI Clap

Build Rust command-line tools that are predictable, scriptable, pleasant in terminals, and easy to ship.

Operating Model

1. Discover the existing CLI contract first: Cargo.toml, src/bin, clap definitions, integration tests, snapshots, release scripts, and README examples.
2. Preserve user-facing command behavior unless the task explicitly asks for a breaking change. If behavior changes, update tests and docs in the same patch.
3. Prefer clap derive for ordinary CLIs. Use the builder API when commands are generated dynamically, hidden/unstable command surfaces need custom construction, or macros make the shape harder to read.
4. Design command output as an API: human output on stdout, diagnostics on stderr, deterministic --json/machine output where automation is expected, and stable exit codes.
5. Keep command handlers thin. Parse into typed arguments, normalize config once, then call library code that tests can exercise without spawning a process.

Reference Map

Open only the section needed for the task:

• references/clap-parser-playbook.md for clap derive/builder design, argument groups, validators, completions, and migration notes.
• references/terminal-contracts.md for stdout/stderr, color, progress, config precedence, error messages, and shell automation rules.
• references/testing-packaging.md for assert_cmd, trycmd, snapshots, binaries, completions, manpages, cargo-dist, and release checks.

Defaults

• Use clap = { features = ["derive", "env"] } when environment variables are part of the contract; otherwise avoid unused features.
• Use camino or Utf8PathBuf only when UTF-8 paths are an explicit invariant. Otherwise keep PathBuf.
• Use anstream/anstyle or clap styling for color-aware output; respect NO_COLOR, CLICOLOR, and non-TTY behavior.
• Use tracing for diagnostics when the CLI has subcommands, network calls, daemon/client modes, or hidden debugging flags.
• Use thiserror for domain errors and miette or color-eyre at the presentation boundary only when rich reports add value.

Verification

For CLI changes, prefer the smallest ladder that proves the contract:

cargo fmt --all --check
cargo test --all-targets
cargo clippy --workspace --all-targets --all-features -- -D warnings

Add focused command tests for new flags, output modes, exit codes, config precedence, and examples shown in docs. Snapshot CLI output only after normalizing volatile paths, timestamps, colors, and ordering.