Rust CLI Clap
Build Rust command-line tools that are predictable, scriptable, pleasant in terminals, and easy to ship.
Operating Model
- Discover the existing CLI contract first:
Cargo.toml, src/bin, clap definitions, integration tests, snapshots, release scripts, and README examples.
- 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.
- 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.
- 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.
- 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.
1---2name: rust-cli-clap3description: Implicit Rust CLI and Clap skill. Use for command-line apps and tools, clap derive or builder APIs, subcommands, flags, config and env precedence, stdin/stdout/stderr contracts, JSON output, exit codes, completions, manpages, shell UX, CLI tests, and binary distribution.4license: MIT5---6
7# Rust CLI Clap
8
9Build Rust command-line tools that are predictable, scriptable, pleasant in terminals, and easy to ship.
10
11## Operating Model
12
131. Discover the existing CLI contract first: `Cargo.toml`, `src/bin`, `clap` definitions, integration tests, snapshots, release scripts, and README examples.
142. 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.
153. 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.
164. 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.
175. Keep command handlers thin. Parse into typed arguments, normalize config once, then call library code that tests can exercise without spawning a process.
18
19## Reference Map
20
21Open only the section needed for the task:
22
23- `references/clap-parser-playbook.md` for `clap` derive/builder design, argument groups, validators, completions, and migration notes.
24- `references/terminal-contracts.md` for stdout/stderr, color, progress, config precedence, error messages, and shell automation rules.
25- `references/testing-packaging.md` for `assert_cmd`, `trycmd`, snapshots, binaries, completions, manpages, `cargo-dist`, and release checks.
26
27## Defaults
28
29- Use `clap = { features = ["derive", "env"] }` when environment variables are part of the contract; otherwise avoid unused features.
30- Use `camino` or `Utf8PathBuf` only when UTF-8 paths are an explicit invariant. Otherwise keep `PathBuf`.
31- Use `anstream`/`anstyle` or `clap` styling for color-aware output; respect `NO_COLOR`, `CLICOLOR`, and non-TTY behavior.
32- Use `tracing` for diagnostics when the CLI has subcommands, network calls, daemon/client modes, or hidden debugging flags.
33- Use `thiserror` for domain errors and `miette` or `color-eyre` at the presentation boundary only when rich reports add value.
34
35## Verification
36
37For CLI changes, prefer the smallest ladder that proves the contract:
38
39```bash
40cargo fmt --all --check
41cargo test --all-targets
42cargo clippy --workspace --all-targets --all-features -- -D warnings
43```
44
45Add 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.
aibot88