[BrewTestBot]

Created by brew bump

---

Created with brew bump-formula-pr.

Details

release notes

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_*:



New
Legacy (still read)




USAGECLI_SHELL_{BASH,ZSH,FISH,PWSH}
USAGE_SHELL_*


USAGECLI_DEBUG
USAGE_DEBUG


USAGECLI_TRACE
USAGE_TRACE


USAGECLI_LOG
USAGE_LOG



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: jdx/usage@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.

View the full release notes at https://github.com/jdx/usage/releases/tag/v6.1.0.

---

[github-actions]

🤖 An automated task has requested bottles to be published to this PR.

Caution

Please do not push to this PR branch before the bottle commits have been pushed, as this results in a state that is difficult to recover from. If you need to resolve a merge conflict, please use a merge commit. Do not force-push to this PR branch.