home / skills / pproenca / dot-skills / rust-clap

rust-clap skill

safe

This skill helps you write, review, or refactor Rust CLIs with clap by following proven design and parsing best practices.

npx playbooks add skill pproenca/dot-skills --skill rust-clap

Review the files below or copy the command above to add this skill to your agents.

Files (46)

SKILL.md

6.2 KB

---
name: rust-clap
description: 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.
---

# 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`](references/type-valueenum-enums.md) - Use ValueEnum for enumerated arguments
- [`type-option-optional`](references/type-option-optional.md) - Use Option for truly optional arguments
- [`type-pathbuf-files`](references/type-pathbuf-files.md) - Use PathBuf for file system arguments
- [`type-vec-multiple`](references/type-vec-multiple.md) - Use Vec for multiple value arguments
- [`type-newtype-semantic`](references/type-newtype-semantic.md) - Use newtypes for semantic distinction
- [`type-bool-flags`](references/type-bool-flags.md) - Use bool for simple flags

### 2. Derive API Patterns (CRITICAL)

- [`derive-parser-entry`](references/derive-parser-entry.md) - Derive Parser for CLI entry point
- [`derive-command-metadata`](references/derive-command-metadata.md) - Use Command attribute for metadata
- [`derive-subcommand-enum`](references/derive-subcommand-enum.md) - Use Subcommand derive for command hierarchies
- [`derive-args-reusable`](references/derive-args-reusable.md) - Derive Args for reusable argument groups
- [`derive-doc-comments`](references/derive-doc-comments.md) - Use doc comments for help text
- [`derive-global-options`](references/derive-global-options.md) - Use Global for cross-subcommand options
- [`derive-propagate-version`](references/derive-propagate-version.md) - Propagate version to subcommands

### 3. Argument Configuration (HIGH)

- [`arg-default-value`](references/arg-default-value.md) - Use default_value for sensible defaults
- [`arg-env-fallback`](references/arg-env-fallback.md) - Use env for environment variable fallback
- [`arg-short-long`](references/arg-short-long.md) - Provide both short and long option names
- [`arg-conflicts-with`](references/arg-conflicts-with.md) - Use conflicts_with for mutually exclusive options
- [`arg-requires`](references/arg-requires.md) - Use requires for dependent arguments
- [`arg-value-name`](references/arg-value-name.md) - Use value_name for descriptive placeholders

### 4. Validation & Parsing (HIGH)

- [`valid-value-parser`](references/valid-value-parser.md) - Use value_parser for custom validation
- [`valid-possible-values`](references/valid-possible-values.md) - Use PossibleValuesParser for string constraints
- [`valid-fromstr-types`](references/valid-fromstr-types.md) - Implement FromStr for domain types
- [`valid-try-parse`](references/valid-try-parse.md) - Use try_parse for graceful error handling
- [`valid-num-args`](references/valid-num-args.md) - Use num_args for value count constraints

### 5. Subcommand Architecture (MEDIUM-HIGH)

- [`subcmd-nested-hierarchy`](references/subcmd-nested-hierarchy.md) - Use nested subcommands for complex CLIs
- [`subcmd-args-struct`](references/subcmd-args-struct.md) - Use struct for subcommand arguments
- [`subcmd-required-help`](references/subcmd-required-help.md) - Require subcommand or show help
- [`subcmd-arg-groups`](references/subcmd-arg-groups.md) - Use ArgGroup for one-of-many requirements
- [`subcmd-external`](references/subcmd-external.md) - Use external subcommands for plugin systems

### 6. Help & Documentation (MEDIUM)

- [`help-shell-completions`](references/help-shell-completions.md) - Generate shell completions with clap_complete
- [`help-next-heading`](references/help-next-heading.md) - Use next_help_heading for organized help
- [`help-after-help`](references/help-after-help.md) - Use after_help for examples and context
- [`help-hide-options`](references/help-hide-options.md) - Hide advanced options from default help

### 7. Error Handling (MEDIUM)

- [`error-exit-codes`](references/error-exit-codes.md) - Use appropriate exit codes
- [`error-context`](references/error-context.md) - Add context to error messages
- [`error-suggestions`](references/error-suggestions.md) - Enable suggestions for typos
- [`error-color-styles`](references/error-color-styles.md) - Use colored output for error visibility

### 8. Testing Patterns (LOW-MEDIUM)

- [`test-assert-cmd`](references/test-assert-cmd.md) - Use assert_cmd for integration testing
- [`test-predicates`](references/test-predicates.md) - Use predicates for flexible assertions
- [`test-temp-files`](references/test-temp-files.md) - Use assert_fs for temporary test files
- [`test-parse-from`](references/test-parse-from.md) - Use parse_from for unit testing parsers
- [`test-trycmd-snapshots`](references/test-trycmd-snapshots.md) - Use trycmd for snapshot testing

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

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

Overview

This skill helps Rust developers design, review, and refactor command-line interfaces built with clap by providing prioritized best practices. It condenses 42 concrete rules across type design, derive patterns, argument configuration, validation, subcommand architecture, help text, error handling, and testing. Use it to make CLIs safer, clearer, and more maintainable.

How this skill works

The skill inspects CLI surface decisions and recommends clap-specific patterns: choosing types (PathBuf, Option, Vec, ValueEnum), using derive macros for Parser/Subcommand/Args, and configuring arguments (short/long names, defaults, env fallbacks). It also checks validation and parsing strategies (value_parser, FromStr), subcommand structure, help organization, error ergonomics, and testing approaches, and points to concrete rules for each concern.

When to use it

Designing a new Rust CLI entry point with clap
Adding or refactoring arguments, flags, or subcommands
Improving help text, completions, or UX for users
Implementing validation, parsing, or domain types for arguments
Writing unit or integration tests for CLI behavior

Best practices

Favor type-driven design: map argument semantics to Rust types (ValueEnum, Option, PathBuf, Vec, newtypes).
Prefer derive APIs (Parser, Subcommand, Args) and doc comments for help text and metadata propagation.
Provide both short and long flags, meaningful value_name, sensible default_value and env fallbacks where appropriate.
Use value_parser, FromStr, and PossibleValuesParser for robust validation and clear error messages.
Design subcommands as nested hierarchies with dedicated structs, require subcommands when necessary, and use ArgGroup for mutually exclusive choices.
Write integration tests with assert_cmd/assert_fs and unit tests using parse_from or try_parse for parsing logic.

Example use cases

Review a repo to replace string-typed path arguments with PathBuf and add validation.
Refactor flat commands into nested subcommands and move shared options to a Global struct.
Add value_parser and FromStr implementations to validate complex domain types at parse time.
Improve user help: add next_help_heading, after_help examples, and generate shell completions.
Write integration tests with assert_cmd and snapshot plugin behaviors using trycmd.

FAQ

When should I use ValueEnum vs FromStr?

Use ValueEnum for enumerations that should appear in help and accept a fixed set of values; implement FromStr for richer domain parsing or when you need custom parse errors or conversions.

How do I decide between ArgGroup and conflicts_with?

Use ArgGroup when the CLI needs a one-of-many selection or grouped validation; use conflicts_with for simple pairwise mutual exclusion between a small number of flags.