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.