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