jdx/usage v6.1.0

v6.1.0: Sharper derives, richer dispatch

on GitHub

This release sharpens the Rust derive framework introduced in 6.0: #[usage(run)] now handles the enum shapes real clap CLIs actually have, help and diagnostics respect the runtime identity of parse_from callers, and flatten-site help headings work. On the CLI itself, settings move to a prefix mise cannot strip, and generated KDL now round-trips multiline help.

Added

Broader #[usage(run)] dispatch (#1221)

The derived dispatch previously required every variant to wrap a named Args type, the whole enum to be sync or async, and the root to hold nothing but its subcommand field. That is now covered:

• Unit and inline variants get a generated {Enum}{Variant} struct you can impl Run on.
• Mixed sync/async: put #[usage(run_async)] on the enum and #[usage(run)] on the variant that should not .await.
• Catch-alls: #[usage(run, external = fallback)] forwards the unmatched argv (and context, if run_with).
• Roots with flags: #[usage(run)] on a struct with --verbose and a required subcommand generates run_command instead of impl Run, so top-level flags are not dropped.
• Skip context: #[usage(no_ctx)] plus run_with_lazy / run_async_with_lazy (FnOnce() -> Ctx) lets commands like version avoid loading a config file.
• output = Type explicitly names the match's Output instead of borrowing it from the first command.

Runtime identity in help, and flatten-site headings (#1220)

parse() already overlays the embedder's computed name / bin. parse_from callers that rendered help through Cli::spec() did not. Cli::render_help and Cli::render_failure now apply the same identity, so vendored parsers stop leaking the portable aube name into help and diagnostics.

#[usage(flatten, next_help_heading = "…")] at the flatten site now groups the unheaded flags of a flattened Args struct — matching clap's behavior — and reaches into subcommand help and generated KDL too.

USAGECLI_* settings prefix (#1213 by @JamBalaya56562)

Because Windows env-var names are case-insensitive, USAGE_DEBUG (a usage-cli setting) collides with usage_debug (a spec's own flag), and mise clears everything starting with usage_ before running a task — including usage-cli's settings. Settings can now be read under USAGECLI_*:

First name set wins. As a side benefit, USAGE_LOG is no longer written back into the environment with set_var, so a spawned script's own log argument survives.

Fixed

• Long help flows like short help. Non-verbatim doc comments wrap the same way for long_help as for help: source-wrapped lines become spaces, indented examples and fenced code blocks keep their breaks, and verbatim_doc_comment is untouched (#1215).
• KDL keeps newlines. Spec::to_kdl emits #"""…"""# raw multiline strings for values that contain newlines, so generated .usage.kdl no longer collapses multi-paragraph help into one giant escaped line (#1215).

Changed

• Removed clap-compatible attribute spellings (a989d26b). Derives now accept only #[usage(...)]. #[command(...)], #[arg(...)], #[value(...)], #[group(...)], and inner synonyms (id, default_value, conflicts_with, value_parser, last, …) still parse, but fail at the source span with a diagnostic telling you the native replacement. Implicit clap-style #[group(...)] generation for one-member groups is gone — requiredness comes from the field type or required.
• Stricter variant validation (#1224): redundant #[usage(run_async)] on an enum variant is now rejected while parsing the attribute.

Documentation

• Complete KDL reference for the spec (#1214).
• Rust framework docs refreshed: sharper framework page (#1222), summarized parser performance page (#1219), combined clap migration guide (#1217), refreshed clap binary-size comparison (#1212), dropped a restated intro line (#1211).
• Benchmark charts added to the Rust and Go pages and comparison methodology clarified (#1209, #1210).

Breaking Changes

• Derive attributes must use #[usage(...)]. Any remaining clap-shaped attributes (#[command], #[arg], #[value], #[group], or their inner synonyms) will now fail to compile with a diagnostic pointing at the replacement. See the clap migration guide for before/after rewrites.
• Implicit single-member #[group(...)] generation is gone. If you relied on it for requiredness, mark the field required or use its type (e.g. non-Option) instead.

Full Changelog: v6.0.0...v6.1.0

💚 Sponsor usage

usage is maintained by @jdx, an open source developer for entire.io, the title sponsor of the jdx.dev open source tools including mise, aube, hk, and more. Work on usage is funded by sponsorships.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider sponsoring at jdx.dev. Every sponsorship helps the project stay independent and moving.