Rust Clap Best Practices

Comprehensive best practices guide for building CLI applications in Rust using clap. Contains 42 rules across 8 categories, prioritized by impact to guide CLI design, argument parsing, and testing.

When to Apply

Reference these guidelines when:

• Designing new Rust CLI applications
• Adding arguments or subcommands to existing CLIs
• Validating and parsing command-line input
• Writing integration tests for CLI tools
• Improving help text and user experience

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Type-Driven Design | CRITICAL | type- | | 2 | Derive API Patterns | CRITICAL | derive- | | 3 | Argument Configuration | HIGH | arg- | | 4 | Validation & Parsing | HIGH | valid- | | 5 | Subcommand Architecture | MEDIUM-HIGH | subcmd- | | 6 | Help & Documentation | MEDIUM | help- | | 7 | Error Handling | MEDIUM | error- | | 8 | Testing Patterns | LOW-MEDIUM | test- |

Quick Reference

1. Type-Driven Design (CRITICAL)

• type-valueenum-enums - Use ValueEnum for enumerated arguments
• type-option-optional - Use Option for truly optional arguments
• type-pathbuf-files - Use PathBuf for file system arguments
• type-vec-multiple - Use Vec for multiple value arguments
• type-newtype-semantic - Use newtypes for semantic distinction
• type-bool-flags - Use bool for simple flags

2. Derive API Patterns (CRITICAL)

• derive-parser-entry - Derive Parser for CLI entry point
• derive-command-metadata - Use Command attribute for metadata
• derive-subcommand-enum - Use Subcommand derive for command hierarchies
• derive-args-reusable - Derive Args for reusable argument groups
• derive-doc-comments - Use doc comments for help text
• derive-global-options - Use Global for cross-subcommand options
• derive-propagate-version - Propagate version to subcommands

3. Argument Configuration (HIGH)

• arg-default-value - Use default_value for sensible defaults
• arg-env-fallback - Use env for environment variable fallback
• arg-short-long - Provide both short and long option names
• arg-conflicts-with - Use conflicts_with for mutually exclusive options
• arg-requires - Use requires for dependent arguments
• arg-value-name - Use value_name for descriptive placeholders

4. Validation & Parsing (HIGH)

• valid-value-parser - Use value_parser for custom validation
• valid-possible-values - Use PossibleValuesParser for string constraints
• valid-fromstr-types - Implement FromStr for domain types
• valid-try-parse - Use try_parse for graceful error handling
• valid-num-args - Use num_args for value count constraints

5. Subcommand Architecture (MEDIUM-HIGH)

• subcmd-nested-hierarchy - Use nested subcommands for complex CLIs
• subcmd-args-struct - Use struct for subcommand arguments
• subcmd-required-help - Require subcommand or show help
• subcmd-arg-groups - Use ArgGroup for one-of-many requirements
• subcmd-external - Use external subcommands for plugin systems

6. Help & Documentation (MEDIUM)

• help-shell-completions - Generate shell completions with clap_complete
• help-next-heading - Use next_help_heading for organized help
• help-after-help - Use after_help for examples and context
• help-hide-options - Hide advanced options from default help

7. Error Handling (MEDIUM)

• error-exit-codes - Use appropriate exit codes
• error-context - Add context to error messages
• error-suggestions - Enable suggestions for typos
• error-color-styles - Use colored output for error visibility

8. Testing Patterns (LOW-MEDIUM)

• test-assert-cmd - Use assert_cmd for integration testing
• test-predicates - Use predicates for flexible assertions
• test-temp-files - Use assert_fs for temporary test files
• test-parse-from - Use parse_from for unit testing parsers
• test-trycmd-snapshots - Use trycmd for snapshot testing

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

| File | Description | |------|-------------| | references/_sections.md | Category definitions and ordering | | assets/templates/_template.md | Template for new rules | | metadata.json | Version and reference information |