rust-clap

Original：🇺🇸 English

Translated

Rust Clap CLI argument parsing best practices. This skill should be used when writing, reviewing, or refactoring Rust CLI applications using clap. Triggers on tasks involving argument parsing, CLI design, subcommands, and command-line interfaces in Rust.

1installs

Sourcepproenca/dot-skills

Added on2026-02-07

NPX Install

npx skill4agent add pproenca/dot-skills rust-clap

SKILL.md Content

View Translation Comparison →

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


type-
derive-
arg-
valid-
subcmd-
help-
error-
test-

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