Rust Cli Clap

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.

Clap Parser Playbook

API Choice

Prefer derive for stable, statically known command trees:

• Keep the root parser small and route work through subcommand handler functions.
• Put repeated option groups in flattened structs.
• Use typed enums with ValueEnum instead of stringly-typed mode flags.
• Use ArgGroup for true mutual exclusion or required-one-of contracts.
• Use value_parser! and domain parsers for validated numbers, durations, URLs, and IDs.

Use the builder API when:

• Commands are plugin-discovered or generated from runtime metadata.
• Experimental commands need hidden aliases or feature-gated registration.
• The command tree is easier to audit as data than as nested derive structs.

Avoid mixing derive and builder without a clear boundary. If a derive parser needs heavy post-processing, move that logic into a typed config normalization layer instead of hiding it in parser attributes.

Argument Design

• Prefer explicit long flags for scripts and stable short flags only for high-frequency terminal use.
• Keep positional arguments rare and obvious. Once there are multiple optional positionals, switch to named flags.
• Use default_value_t only when the default is part of the public contract. Otherwise compute defaults after merging config/env/CLI sources.
• Use Option<T> for absence and a separate enum for semantic modes. Avoid sentinel strings such as "auto" unless auto is a real mode.
• For path inputs, accept PathBuf; canonicalize only when required, and report the original path in user-facing errors.

Precedence Model

State precedence explicitly in docs and tests. A solid default:

1. CLI flags 2. Environment variables 3. Config files 4. Project defaults 5. Built-in defaults

Do not let clap environment values silently bypass config validation. Parse and normalize into one domain config before execution.

Help and Discovery

• Use command names as verbs: sync, check, init, serve.
• Keep help examples current by testing them.
• Generate shell completions and man pages for shipped CLIs when the distribution channel supports them.
• Hide truly internal flags with hide = true, but avoid undocumented "support-only" behavior for public workflows.

Migration Notes

When upgrading clap, check:

• Derive attribute renames or semantic changes.
• Color/styling behavior.
• Error message snapshots.
• Shell completion output.
• env feature availability and variable naming.

Use official clap docs and changelogs for version-specific behavior before changing public parser contracts.

Terminal Contracts

Streams

• stdout is for primary command output.
• stderr is for diagnostics, progress, warnings, and trace-style information.
• JSON, NDJSON, CSV, or other machine output must be complete, deterministic, and free of human prose.
• Progress bars belong on stderr and should disable automatically when stderr is not a terminal.

Exit Codes

Keep exit codes small and documented for automation-heavy tools:

• 0: success
• 1: general runtime failure
• 2: invalid user input or usage
• Additional codes only when callers can realistically branch on them.

Avoid panics for expected user errors. Convert domain failures into typed errors and a presentation layer that gives enough context to act.

Color and Formatting

• Respect NO_COLOR and non-TTY output.
• Provide --color auto|always|never for tools with rich output.
• Use tables only for humans. Provide JSON for scripts.
• Keep terminal width responsive; avoid wrapping data in ways that break copy/paste.

Logging and Verbosity

Prefer a consistent verbosity shape:

• Default: quiet unless user action is needed.
• -v/--verbose: explain major steps.
• -vv or tracing filter: detailed diagnostics.
• --quiet: suppress non-essential human output.

Do not log secrets, tokens, URLs with credentials, or full request bodies by default.

Config and Environment

Use an explicit source model. When reporting effective config, include source labels but redact secrets.

Avoid hidden environment variables. If an env var is supported, document it, test it, and include it in help when appropriate.

Testing and Packaging

Test Shape

Use direct library tests for domain behavior and process-spawning tests for CLI contracts.

Useful crates:

• assert_cmd for invoking binaries.
• predicates for stdout/stderr assertions.
• trycmd for command transcript tests.
• insta for normalized snapshots.
• tempfile for isolated filesystem state.

Test at least:

• Parser success/failure for new flags and subcommands.
• Config/env/CLI precedence.
• stdout/stderr separation.
• JSON schema or shape when machine output exists.
• Exit codes.
• Help examples that users will paste.

Snapshot Discipline

Normalize:

• absolute paths
• platform path separators when cross-platform
• timestamps
• ordering from maps, filesystems, and concurrent work
• ANSI color unless color itself is under test

Do not snapshot huge help output just because it is easy. Assert stable behavior and snapshot only the text that is intentionally public.

Distribution

For serious binaries, consider:

• cargo-dist for release artifacts and installers.
• release-plz for changelog/release automation.
• cargo-binstall support where appropriate.
• generated completions/manpages included in packages.

Ship Cargo.lock for application binaries. Set rust-version deliberately and test the minimum supported Rust version when claiming MSRV support.