feat(cli): parse usage's own command line with the parser usage ships

[jdx]

Stacked on #963, the usage-rs facade.

usage is now its own first adopter. Its command structs, root, and command enums use the usage-rs facade instead of Clap, and --usage-spec prints Cli::to_kdl() from the same tables that parsed the command line.

What goes away

• clap, clap_usage, and the clap-sort dev dependency
• tests/clap_sort.rs; declaration order is held by the spec
• the duplicated command-effect tables; effects now live on the commands they describe
• the empty Sponsors struct; unit subcommands are supported directly
• runtime checks for relationships the spec can express

Migration shape

The declarations remain close to their former Clap layout:

• inferred shorts use #[usage(short, long)]
• command aliases live on their command structs, e.g. #[usage(alias = "c", alias_hidden("complete", "completions"))]
• positive dependencies use requires, including --cache-key → --usage-cmd and --out-dir → --multi
• aliases written on enum variants still merge with struct aliases for compatibility
• deliberately formatted docs keep #[usage(verbatim_doc_comment)]
• path hints keep value_hint = usage_rs::ValueHint::FilePath or DirPath from usage’s own runtime type
• subcommand payloads stay unboxed as they were under Clap; Box<T> remains an optional size optimization

The four shell commands are separate derived structs flattening a shared group. A single destination struct cannot identify which enum variant selected it, so a macro keeps their common declaration in one place.

Parity gaps closed by the stack

• required subcommands survive KDL generation (feat(derive): say that a command cannot be run alone, which it knew and did not write #937)
• strict unknown-flag behavior is inherited by subcommands (fix(argv): inherit unknown_flags, which reached one command out of a tree #939)
• command-owned visible and hidden aliases are supported (feat(derive): keep command aliases on their args #946)
• duplicate non-repeatable flags are rejected (fix(argv): reject duplicate flags #945)
• a missing required subcommand prints the available command choices (fix(argv): show choices when a subcommand is required #947)
• verbatim doc-comment layout is preserved on commands, fields, and variants (feat(derive): preserve verbatim doc comments #949)
• file and directory value hints reach native and emitted completions (feat(derive): support path value hints #951)

The emitted spec still intentionally gains metadata the Clap bridge dropped, including JDX_USAGE_BIN on --usage-bin, preserved multiline long help, the manpage description, and the correct binary name usage.

Verification

• mise run render
• cargo test --all --all-features
• cargo clippy --all --all-features --all-targets -- -D warnings
• direct binary checks for no-argument help, duplicate flags, command aliases, and positive requirements

This PR was generated by Codex.

---

Note

Medium Risk
Changes how the primary usage CLI is parsed and documented (including --completions UX), but behavior is covered by updated integration tests and is an intentional migration to the shipped parser.

Overview
The usage binary dogfoods usage-rs: command structs use #[derive(usage_rs::Cli)] / #[usage(...)] instead of Clap, and --usage-spec emits Cli::to_kdl() from the same parse tables that handle argv. Clap, clap_usage, and clap-sort are removed, along with the post-hoc command_effects patch table—effect, requires, overrides, and similar metadata now live on the declarations.

Root CLI shape is corrected in spec and docs: --completions <SHELL> is a long flag (not a positional), with an explicit multi-line usage synopsis for usage <COMMAND> / --completions / --usage-spec. Shell runner commands (bash, fish, zsh, powershell, exec) use unknown_flags = "value" so script arguments can include unknown flags.

Help and manpages gain support for an optional root usage string on Spec (derive + KDL emission); root help/man synopsis prefer that over generated lines. Generated assets (usage.usage.kdl, usage.1, Fig spec, CLI reference markdown, snapshots) are refreshed to match.

^{Reviewed by Cursor Bugbot for commit 3aba1aa. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• New Features

  • Added --completions <SHELL> for selecting a completion shell.
  • Improved command validation, aliases, defaults, environment settings, and file-output completion hints.
  • Shell commands now forward unrecognized arguments as script values.
  • Added clearer help text and descriptions for generation commands.

• Documentation

  • Updated CLI references, manpages, usage specifications, and shell documentation to reflect revised options and behavior.

Replaces #936 after flipping the facade and CLI layers.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 2a38dfe0-5a59-4d16-a52e-7aeaabaa76c6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR migrates the usage binary from Clap to its own usage-rs parser and generates its self-description from the same metadata used for parsing.

• Replaces Clap-derived CLI declarations and dispatch with usage-rs derives.
• Adds explicit root synopsis metadata and propagates it through KDL, help, and manpage rendering.
• Moves command effects into command declarations and refreshes generated specifications, documentation, and completion assets.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
cli/src/cli/mod.rs	Migrates root parsing, diagnostics, help/version handling, and command dispatch to the shipped parser.
argv/src/spec.rs	Adds explicit synopsis metadata and serializes it safely into generated KDL.
argv/src/help.rs	Uses the explicit synopsis for root help while preserving generated usage lines for subcommands.
conformance/tests/spec_roundtrip.rs	Adds exact round-trip coverage for a multiline explicit synopsis containing quoted text.
lib/src/docs/manpage/renderer.rs	Incorporates explicit root synopsis alternatives into generated manpages.

_{Reviews (2): Last reviewed commit: "fix(help): honor explicit usage synopsis" | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 47d85ed. Configure here.}