clap-rs/clap

This system is the clap library, a comprehensive Rust toolkit for building command-line interfaces. It provides a dual API approach, supporting both a programmatic builder pattern and a declarative derive macro system for defining arguments, subcommands, and value parsing. The ecosystem extends beyond core parsing to include automated generation of shell completions for major shells and man pages, alongside a standalone lexer for custom parsing needs.

16 changes.

This period focused on migrating the project to clap v4, introducing a new derive macro system with Parser, Args, Subcommand, and ValueEnum traits to replace legacy implementations. The work included extensive refactoring of the derive utilities, comprehensive test coverage for both builder and derive APIs, and the introduction of shell completion capabilities via the clap\_complete crate.

32 changes.

This period focused on restructuring the codebase for clap v5 by extracting clap\_lex and stabilizing clap\_builder to improve derive build times. It introduced new standalone crates for man page generation (clap\_mangen) and Nushell completions (clap\_complete\_nushell), while significantly enhancing error reporting, help text styling, and shell completion capabilities.

13 changes.

This period focused on introducing a new Ahead-Of-Time (AOT) completion generation module with fallible APIs and a shell-agnostic completion engine supporting custom candidate logic. Comprehensive test suites were added for man page generation, lexer behavior, and dynamic completions across Bash, Elvish, Fish, PowerShell, and Zsh. The work also included new examples for typed derive parsing and an environment-based activation API for shell completions.

Added new examples in the \examples/derive\_ref\ directory demonstrating how to manually implement \FromArgMatches\ and \Args\/\Subcommand\ traits to integrate derived argument structures with hand-built \clap\ commands. The \augment\_args.rs\ and \augment\_subcommands.rs\ examples show how to augment a base \Command\ with derived types, while \flatten\_hand\_args.rs\ and \hand\_subcommand.rs\ illustrate manual trait implementations for flattening arguments and handling subcommands, respectively. An accompanying \interop\_tests.md\ file provides console output tests verifying the behavior of these interop patterns.

_examples/derive\ref · high confidence

A new example file (examples/man.rs) demonstrates how to generate man pages using the clap\_mangen library with the modern clap v4 API (Command and arg! macros). The example shows configuring a CLI application with arguments, subcommands, and help text, then rendering the output to stdout for piping to a man page viewer.

_clap\mangen/examples · high confidence

The examples directory now includes a comprehensive set of new demonstrations for the clap library, covering both the derive and builder APIs. New entries include a basic greeting demo, escaped positional arguments, and a detailed \find\-style example for position-sensitive flags. Subcommand patterns are illustrated with \git\-like interfaces (including default subcommands, external subcommands, and configurable aliases) and \pacman\-style flag-based subcommands. Additionally, multicall behavior is demonstrated with \busybox\ and \hostname\-style applets, and a read-eval-print loop (REPL) example shows how to parse repeated command lines.

examples · high confidence

Added example files (nushell\_completion.rs, sub\_subcommands.rs, test.rs) demonstrating how to generate Nushell completions using clap\_complete\_nushell, including basic usage, sub-subcommand handling, and comprehensive argument/option testing.

_clap\_complete\nushell/examples · high confidence

The examples/typed-derive directory now includes a complete runnable example (main.rs) and sub-modules (implicit, builtin, fn\_parser, custom, foreign\_crate) with corresponding documentation (markdown files). This addition demonstrates how to use clap's derive feature for various value parsing scenarios, including implicit FromStr parsing, built-in parsers for discrete numbers and foreign enums, hand-written function parsers for key-value pairs, and custom TypedValueParser implementations.

examples/typed-derive · high confidence

This change introduces the clap\_complete\_nushell crate, which generates Nushell completions for CLIs built with clap. The initial release (v4.3.0) includes the core library, documentation, and license files, enabling users to integrate Nushell shell completions into their clap-based applications.

_clap\_complete\nushell · high confidence

The clap\_mangen crate is introduced, allowing users to generate ROFF man pages from clap Command definitions. The initial version (0.3.3) includes fixes to hide hidden positionals in the SYNOPSIS, show Command::override\_usage in the synopsis, and mark ArgGroups as required in the synopsis when needed. It also requires the 'env' feature for environment variable support and sets the MSRV to 1.85.

_clap\mangen · high confidence

Adds a new \clap\_complete\_nushell\ crate that generates Nushell completion scripts for clap-based CLIs. The generator creates Nushell modules containing completions for subcommands and arguments, mapping clap's \ValueHint\ types (such as \DirPath\ and \FilePath\) to appropriate Nushell types like \directory\ and \path\, and handling possible values for argument completion.

_clap\_complete\nushell/src · high confidence

A new \clap\_mangen\ crate has been added to generate manual pages in ROFF format from \clap::Command\ definitions. It provides a \Man\ struct for building individual pages and a \generate\_to\ function to recursively generate pages for a command tree, respecting visibility settings like hidden subcommands and arguments.

_clap\mangen/src · high confidence

A new \CompleteEnv\ API is added to \clap\_complete\, allowing applications to activate shell completions by setting an environment variable (default \COMPLETE\) rather than relying on a CLI argument or subcommand. This integration supports Bash, Elvish, Fish, PowerShell, and Zsh, generating shell scripts that call the application binary to provide completions dynamically. The implementation includes specific adapters for each shell to handle registration and completion logic, offering a flexible and performant way to enable tab-completion without interfering with other CLI logic.

_clap\complete/src/env · high confidence

The \clap\_complete\ crate now provides a new set of Ahead-Of-Time (AOT) completion generators for Bash, Elvish, Fish, PowerShell, and Zsh. These generators implement a fallible \try\_generate\ method, allowing callers to handle potential I/O errors during script generation rather than panicking. The implementation includes shell-specific fixes such as proper single-quote escaping in PowerShell, deduplication of Bash subcommand cases, and improved handling of optional value arguments in Zsh.

_clap\complete/src/aot/shells · high confidence

The \clap\_derive\ crate now provides a new set of derive macros (\Parser\, \Args\, \Subcommand\, \ValueEnum\) that implement the \clap::Parser\, \clap::Args\, \clap::Subcommand\, and \clap::ValueEnum\ traits. These macros generate the necessary code to parse command-line arguments into Rust structs and enums, supporting features like subcommands, flattened arguments, and value enumeration. This replaces the previous \Clap\ derive macro and aligns with the new \clap\ v4 API.

_clap\derive/src/derives · high confidence

The \clap\_complete\ crate now exposes a new \aot\ (ahead-of-time) module that provides APIs for generating shell completions at compile-time (\generate\_to\) or runtime (\generate\). This module centralizes the \Shell\ enum and \Generator\ trait, allowing users to easily integrate prebuilt completion generation into their CLI applications without managing the underlying shell-specific logic manually.

_clap\complete/src/aot · high confidence

The \clap\_complete\ crate now exposes a new, shell-agnostic completion engine located in \clap\_complete/src/engine\. This change introduces a core \complete()\ function that performs completion logic independently of any specific shell, returning a list of \CompletionCandidate\ objects. These candidates support rich metadata including help text, grouping tags, display ordering, and visibility controls. The engine also provides new extension traits (\ArgValueCompleter\, \ArgValueCandidates\, \SubcommandCandidates\) that allow users to attach custom completion logic to arguments and subcommands, enabling features like index-aware completion for multi-value arguments and custom external subcommand completion.

_clap\complete/src/engine · high confidence

The \clap\_complete\ crate is introduced, providing shell completion generation capabilities. It exposes a static (ahead-of-time) API via the \aot\ module for generating completions at compile-time or runtime, alongside a new dynamic completion engine (\engine\ module) available behind the \unstable-dynamic\ feature flag. This engine introduces \ArgValueCompleter\ and \ArgValueCandidates\ for custom value completion, \PathCompleter\ for file-system paths, and re-exports \ValueHint\ from clap. The public API also includes deprecated compatibility shims (\generator\, \shells\) that redirect to the new \aot\ module structure.

_clap\complete/src · high confidence

The \clap\_lex\ crate is now available as a separate, minimal, and flexible command-line parser that processes arguments as a stream of tokens. This new module provides \RawArgs\ for iterating over command-line arguments and \OsStrExt\ for safe string operations on \OsStr\, allowing users to build custom parsers without the full \clap\ dependency.

_clap\lex/src · high confidence

Added four new examples in the clap\_complete crate to help users implement shell completions: \completion-derive.rs\ and \completion.rs\ showcase how to use \ValueHint\ attributes (for paths, URLs, emails, etc.) with both derive macros and builder API; \dynamic.rs\ demonstrates runtime dynamic completions using \CompleteEnv\; and \exhaustive.rs\ provides a comprehensive test suite covering various argument types, actions, quoting, and subcommands.

_clap\complete/examples · high confidence

Added the \src/\_derive\ module containing the reference documentation and tutorial for the \clap\ derive API. This includes a step-by-step tutorial (\\_tutorial.rs\) covering quick starts, argument configuration, validation, and subcommands, as well as a comprehensive reference guide (\mod.rs\) detailing derive traits (\Parser\, \Args\, \Subcommand\, \ValueEnum\), command/arg attributes, and field types to help users adopt the declarative derive-based approach.

_src/\derive · high confidence

The \clap\_builder\ crate now exposes the \Parser\, \Args\, and \Subcommand\ traits in its public API, enabling users to derive command-line argument parsing directly on their structs. Additionally, \Command::mut\_args\ and \MKeyMap::mut\_args\ have been added, allowing developers to programmatically modify all arguments in a command definition after construction.

_clap\builder/src · high confidence

The tutorial\_derive directory now includes a complete set of new examples (01\_quick through 05\_01\_assert) demonstrating how to build command-line interfaces using the clap derive macros. These examples cover core features such as flags, options, positional arguments, subcommands, default values, enums, custom parsing, and argument relations, providing users with updated, idiomatic patterns for constructing CLIs.

_examples/tutorial\derive · high confidence

The crate now includes dedicated documentation modules (\\_concepts\, \\_faq\, \\_features\, \\_tutorial\) that are conditionally compiled behind the \unstable-doc\ feature flag. These modules provide in-depth explanations of CLI concepts (such as argument parsing and value parsing), a FAQ comparing clap to other libraries, a reference for available feature flags, and a comprehensive tutorial for the builder API. The \lib.rs\ file exposes these modules when the feature is enabled, enhancing the discoverability of documentation for users learning how to use the library.

src · high confidence

The \clap\_builder/src/util\ module has been expanded with several new internal components to support the refactored builder architecture. This includes \AnyValue\ and \AnyValueId\ for type-safe, downcastable value storage with debug-friendly type names, and a new \Id\ type for argument identifiers that supports conversion from \Cow\<'static, str\>\, \String\, and \&str\. A \ColorChoice\ enum has been added to manage output coloring (Auto, Always, Never) with \ValueEnum\ support for CLI parsing. Additionally, new internal data structures \FlatMap\ and \FlatSet\ provide insertion-order-preserving collections backed by vectors, an \Escape\ helper standardizes string quoting for help text, and a \ChildGraph\ structure manages hierarchical relationships. These changes consolidate escaping logic and improve type safety for internal argument handling.

_clap\builder/src/util · high confidence

The error reporting system has been redesigned to provide richer, more helpful feedback to users. By default (when the \error-context\ feature is enabled), errors now include detailed context such as the specific invalid argument, valid alternatives, and usage hints, styled to follow the rustc diagnostic guide. A new \ErrorFormatter\ trait allows users to swap the default \RichFormatter\ for a simpler \KindFormatter\ or a custom implementation, giving full control over how error messages are displayed. This change improves the developer experience by making command-line errors easier to understand and debug.

_clap\builder/src/error · high confidence

The command-line lexer has been pulled out of the main clap repository into its own independent crate, clap\_lex. This change introduces a dedicated CHANGELOG, README, and contribution guide for the new crate, while license files are symlinked to the parent project. Users can now depend on clap\_lex separately, allowing for independent versioning and updates of the lexer component.

_clap\lex · high confidence

The argument matching logic has been relocated from the main clap crate into the new clap\_builder crate. This change introduces the ArgMatches, MatchedArg, and ValueSource types within clap\_builder/src/parser/matches, establishing the foundation for how parsed command-line arguments are stored and accessed. This structural shift is part of the broader effort to split clap\_builder for faster derive builds.

_clap\builder/src/parser/matches · high confidence

The argument parsing logic in \clap\_builder/src/parser\ has been restructured into distinct, focused modules: \arg\_matcher.rs\ now handles tracking matched arguments and propagating global values, \validator.rs\ manages conflict and requirement validation (including exclusive argument checks), \error.rs\ defines the \MatchesError\ type for internal assertion failures, and \parser.rs\ contains the core tokenization and state-machine logic. This separation clarifies the parsing flow, isolates validation rules, and improves maintainability without changing the external CLI behavior.

_clap\builder/src/parser · high confidence

The \clap\_bench\ crate has been restructured to use the \divan\ benchmarking framework instead of the previous implementation. This change introduces new benchmark files (\complex.rs\, \empty.rs\, \ripgrep.rs\, \rustup.rs\, \simple.rs\) that measure CLI parsing performance for scenarios ranging from simple argument lists to complex ripgrep and rustup simulations. Users running these benchmarks will now use \divan\ for execution, which may alter benchmark output formats and runtime characteristics compared to the prior setup.

_clap\bench · high confidence

The \clap\_builder\ module has been reorganized into distinct source files (action, arg, command, etc.) to improve build times and maintainability. This change stabilizes the help text styling system, allowing users to customize terminal output colors and formatting via \Command::styles\ and \StyledStr\. It also introduces an Extension API (\Extensions\) for attaching custom data to \Arg\ and \Command\ instances, and adds new builder methods like \Command::mut\_args\ and \Command::mut\_subcommands\ for easier runtime modification of the CLI definition.

_clap\builder/src/builder · high confidence

The parser now uses the Jaro string similarity algorithm instead of the previously flawed Jaro-Winkler implementation to generate 'did you mean' suggestions for misspelled flags and subcommands. This change specifically addresses issue \#4660, where strings sharing a long common prefix (10+ characters) were incorrectly treated as perfect matches. The new logic correctly ranks similar options, ensuring users receive accurate suggestions for typos like 'alignmentScorr' matching 'alignmentStart' or 'alignmentScore'.

_clap\builder/src/parser/features · high confidence

The help output text-wrapping logic has been refactored to correctly calculate display widths by ignoring ANSI escape codes, ensuring that colored or styled help text wraps at the intended visual column rather than the byte length. Additionally, the wrapper now preserves block indentation on wrapped lines, so multi-line help descriptions maintain their visual structure instead of collapsing to the left margin.

_clap\builder/src/output/textwrap · high confidence

The \clap\_complete\ AOT (Ahead-of-Time) generator module now exposes a \Generator\ trait that includes a new \try\_generate\ method, allowing completion generation to return errors instead of panicking. This change is accompanied by a new \utils\ module providing helper functions for extracting subcommands, short/long options, and possible values from a \clap::Command\, along with tests for these utilities.

_clap\complete/src/aot/generator · high confidence

The internal utility modules for the derive macro have been restructured and expanded. A new doc\_comments module handles comment extraction and formatting, including optional markdown parsing via the unstable-markdown feature. The type system (ty.rs) now recognizes Vec\<Vec\<T\>\> structures, enabling support for deriving grouped options for nested vectors when the unstable-v5 feature is enabled. Additionally, error handling utilities (error.rs) and a span-attached type wrapper (spanned.rs) have been introduced to improve code clarity and error reporting.

_clap\derive/src/utils · high confidence

The help and usage text generation logic in \clap\_builder/src/output\ has been restructured into dedicated modules (\fmt.rs\, \help.rs\, \help\_template.rs\, \usage.rs\). This refactoring introduces a \Colorizer\ for consistent stream printing, separates the help template engine from the help writer, and consolidates usage string creation. Users benefit from more maintainable internal styling and formatting, which supports upcoming features like flattened help and improved alias display without changing the external API.

_clap\builder/src/output · medium confidence

This release updates the \clap\_complete\ crate to version 4.6.11, introducing a fix for the Zsh generator to correctly escape possible values that lack a help message. The changelog also documents previous fixes, including making Bash function names POSIX compatible (4.6.9) and detecting \pwsh\ as \powershell\ (4.6.7).

_clap\complete · high confidence

The tutorial builder examples have been rewritten to align with the clap v4 API, replacing the legacy \App\ and \AppSettings\ with \Command\ and functional configuration methods. The examples now utilize the \command!\ macro for automatic metadata, the \arg!\ and \value\_parser!\ macros for argument definition, and \ArgAction\ for handling flags and counts. Additionally, the examples demonstrate modern patterns such as \ValueEnum\ for typed argument parsing, \ArgGroup\ for argument relations, and \debug\_assert\ for validating command configuration.

_examples/tutorial\builder · high confidence

The clap\_builder crate now includes its own README, CONTRIBUTING, and license symlink files, clarifying its role as the builder implementation for clap and directing users to the main repository for broader contribution guidelines. This structural change supports the separation of the builder logic, which aims to improve derive build times, by providing clear documentation and licensing context specific to this component.

_clap\builder · medium confidence

The \clap\_derive\ crate has been rewritten for version 3.0, introducing new derive macros (\Parser\, \Subcommand\, \Args\, \ValueEnum\) that replace the previous \Clap\ and \ArgEnum\ derives. The attribute system has been restructured to support multiple attribute names (\clap\, \structopt\, \command\, \arg\, \group\) and a new \MagicAttrName\ enum for handling special attributes like \skip\, \flatten\, and \subcommand\. The implementation now uses a new \Item\ struct to represent parsed arguments and commands, and includes dummy implementations for error handling that allow compilation to continue with errors. This change represents a significant behavioral shift in how command-line arguments are defined and parsed, requiring users to update their derive usage and attribute syntax.

_clap\derive/src · high confidence

The clap\_derive crate now includes its own README, CONTRIBUTING guide, and license symlinks, clarifying that it is an internal macro implementation rather than a user-facing library. This change improves discoverability of derive-specific documentation and contribution guidelines for developers integrating or extending the derive functionality.

_clap\derive · high confidence

Add comprehensive shell completion test suite; Added Elvish dynamic completion snapshot with environment isolation; Added Fish shell completion test snapshots; Added Nushell completion snapshot tests; Added Zsh dynamic completion test snapshots; Added comprehensive Nushell completion tests; Added comprehensive test suite for man page generation; Added comprehensive test suites for macros, examples, and UI behavior; Added integration tests for clap\_complete examples; Added lexer and parsed argument tests; Added snapshot tests for clap\_mangen roff output; Added snapshot tests for shell completions; Added stdio-fixture binary for testing help and styling output; Comprehensive builder API test coverage; Expanded UI tests for derive macro validation; Expanded test coverage for clap\_derive functionality; Updated Bash completion snapshot for dynamic environment variables; Updated Fish shell completion test snapshots; Updated Nushell completion snapshots for clap\_complete\_nushell; Updated shell completion test snapshots for Bash, PowerShell, and Zsh.

This release updates the clap crate and its workspace members (clap\_builder, clap\_derive, clap\_complete, clap\_mangen, clap\_lex) to version 4.6.7. The project has migrated to the Rust 2024 edition and raised the Minimum Supported Rust Version (MSRV) to 1.85. Key dependency updates include syn 3.0.2 for clap\_derive, anstream 1.0.0 and anstyle 1.0.14 for clap\_builder, and terminal\_size 0.4.4. The release also introduces an \unstable-v5\ feature flag in clap\_builder and clap\_derive, and updates dev-dependencies like snapbox to 1.2.0.

(dependencies) · high confidence

Add project governance and development configuration files; Documentation: Cookbook examples now include Builder and Derive API variants.

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 60 → 67 (+6.7)
• Rubric changed (rubric-2026.09.8 → rubric-2026.09.16) — scores are not directly comparable.

• Code Health 87 → 87 (-0.0)
• Architecture 99 → 99 (-0.5)
• Maturity 52 → 55 (+3.4)
• Readiness 71 → 71 (+0.1)
• Security 52 → 77 (+25.4)

• Documentation: no installation or build instructions (README.md)
• Duplicated block (7 lines × 2) (clap_derive/src/item.rs)
• Duplicated block (8 lines × 2) (clap_derive/src/item.rs)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• …and 52 more

• Dependency hygiene PARTLY measured — Cargo dependencies read, dependency currency not (crates.io unreachable)
• Duplicated block (10 lines × 2) (clap_derive/src/item.rs)
• Duplicated block (5 lines × 2) (clap_derive/src/item.rs)
• Duplicated block (8 lines × 2) (clap_derive/src/item.rs)
• High: security finding (details withheld)
• Highly redundant and confusing getter methods for aliases. There are multiple methods to retrieve aliases with overlapping semantics (visible vs all, short vs long, combined). The return types are inconsistent (char vs str vs impl Iterator), suggesting internal implementation details are leaking or the API is unstable. Specifically, get_visible_short_aliases and get_all_short_aliases returning char (singular) is suspicious for a list of aliases.
• Hotspot: clap_derive/src/attr.rs (clap_derive/src/attr.rs)
• Inconsistent naming and return types for parsing operations. get_matches returns ArgMatches directly (panicking on error), while try_get_matches returns ClapResult. Furthermore, get_matches has no from variant for custom iterators, forcing users to use try_get_matches_from or convert iterators manually. The naming convention mixes 'get' (blocking/panicking) and 'try' (result-returning) inconsistently across input sources.
• Inconsistent naming for subcommand lookup. Command uses find_subcommand, whereas Arg uses get_id, get_help, etc. More importantly, find_subcommand returns Self (the subcommand itself), which is inconsistent with get_arguments which returns an iterator. If it returns Self, it should likely be get_subcommand to match the get_* pattern for retrieval, or find_* should return an Option<Self> to indicate failure, which is the standard Rust pattern for 'find' operations.
• Inverted test pyramid
• Members sharing a duplicated core (4 members, 50+ identical tokens) (clap_derive/src/derives/args.rs)
• No ADRs found
• Off the main sequence: clap_lex
• Off-boarding risk: anonymized user #1
• Redundant _os suffixed methods for default values. default_value and default_value_os appear to do the same thing, as do their plural variants. Since OsStr is the native OS string type in Rust, and Into<OsStr> is accepted by both, the distinction is unclear and likely unnecessary, adding API surface without clear benefit.
• Redundant/Confusing naming for argument count configuration. number_of_values takes a single usize (count), while num_args takes a ValueRange (min/max). In clap, these often map to the same underlying CLI flag (--num-args), but the API exposes two distinct methods with different semantics and input types, leading to confusion about which to use for simple fixed counts vs ranges.

• 23 commits — 21 feature/other, 2 fixes

• (root) — 6 commits
• (repo) — 5 commits
• .github/workflows — 3 commits
• clap_builder/src — 2 commits
• clap_complete/tests — 2 commits
• tests/derive_ui — 2 commits
• clap_complete/CHANGELOG.md — 1 commit
• clap_complete/Cargo.toml — 1 commit
• clap_complete/src — 1 commit

• fix: Merge pull request #6526 from bonnefoa/fix-completion-escape
• fix: fix(clap_complete): Fix value escape in zsh completion
• change: Merge pull request #6521 from r-near/feat/derive-deferred-initialization
• change: Merge pull request #6528 from epage/template
• change: Merge pull request #6535 from epage/action
• change: chore(ci): Pin actions
• change: chore(ci): Remove unused bench job
• change: chore(ci): Resolve conflict
• change: chore(deps): Update Rust crate trybuild to v1.0.120 (#6509)
• change: chore(release): Simplify replacements
• change: chore: Release
• change: chore: Release
• change: chore: Rename master to main
• change: chore: Update from _rust template
• change: docs(ai): Explicitly exclude shell script logic
• change: docs: Update changelog
• change: docs: Update changelog
• change: feat(derive): Defer enum subcommand initialization
• change: style: Make clippy happy
• change: style: Make rustfmt happy
• …and 3 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

clap-rs/clap was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.