github jdx/usage v6.2.0
v6.2.0: Embedded parsing, richer specs, and a redesigned help page
on GitHub

5 hours ago

Added

  • Embedded parse outcomes. embedded::outcome and the derive-generated Cli::embedded_outcome / embedded_outcome_into let N-API, WASM, editor, and test-runner hosts parse without terminating the process, returning a rendered Outcome::Exit with stream and clap-compatible status (#1250, #1270, #1281).
  • Structured diagnostic reports. diagnostic::report returns a stable Code, subject, and optional ArgvSpan (index plus byte offsets into OsStr) so hosts can label parse failures without scraping terminal text (#1255).
  • Opt-in response files. usage::response::expand pre-parses @file arguments with shell-style quoting, nested includes, @@ escaping, and cycle detection — kept off the zero-allocation parse path (#1259).
  • Ordered argument groups. #[usage(multiple)] on an ArgGroup enum collects related flags like -A/-W/-D into Vec<T> in argv order (#1271).
  • Value-carrying argument groups. ArgGroup tuple variants now declare one value-taking flag (Migrate(Source), StdinFilepath(PathBuf)), bound through FromStr, lossless path conversion, or ValueEnum (#1253).
  • Typed command finalization. #[usage(validate_with = …)] runs command-wide invariants after field conversion, and #[usage(try_into = DomainType)] adds parse_into* entry points that finalize through TryFrom (#1254).
  • Runtime-computed defaults. default_fn evaluates a typed default at parse time, with default_note for help prose that describes it honestly (#1256).
  • Dynamic command catalogs. New usage-dynamic crate merges runtime-discovered plugin specs into a derived host's help, completion, and parsing via Catalog::builder, attaching to a static external_subcommand catch-all (#1275).
  • Addressable help topics. help::topics and help::render_topic render a single standard or help_heading section without inventing fake subcommands (#1257).
  • Inline formatting in help text. Coloured --help renders Markdown-style bold, italic, inline-code, and strikethrough spans in prose, leaving plain and piped output unchanged (#1245).
  • Elvish shell completions. Elvish joins bash, zsh, fish, PowerShell, and Nushell as a first-class completion target (#1243).
  • Semantic completion candidates. Candidates carry a kind (Command, Flag, File, Directory, Value) so PowerShell can use native CompletionResult types, plus a display label so zsh and PowerShell can show a richer name while inserting value (#1239, #1242).
  • Path extension filters. Specs declare type="path:toml,yaml" (or use .extensions("toml", "yaml") on FilePath/AnyPath) and every generated completion script filters accordingly; directories still traverse (#1240).
  • Completion traces. Public CompletionTrace records words, prefix, command path, cursor owner, separator state, candidates, and shell path fallback for a Tab answer (#1241).
  • Grouped help template sections. {{grouped_args}}, {{ungrouped_args}}, {{grouped_flags}}, and {{ungrouped_flags}} let templates interleave named help_heading groups with default lists (#1251).
  • Section prose on headings. heading("Ignore Files", help = "…") (and heading "Title" help="…" in KDL) puts a sentence under a named section, next to the entries it explains (#1282).
  • Command outputs, exit codes, and media types. Specs declare output blocks with text/JSON/JSONL framing, selectors, defaults, JSON Schemas (including schema file="…"), an optional media_type, and documented exit codes — surfaced through derives, MCP, generated Python/TypeScript SDKs, Markdown, and manpages (#1249, #1274).
  • Semantic note and warning blocks. #[usage(note = "…", warning = "…")] (or KDL note/warning children) render as labeled admonitions in long help and portable Markdown blockquotes (#1273).
  • Surface availability metadata. #[usage(surface = "…", available_if(…))] carries descriptive audience labels through KDL, JSON, docs, and conformance tables without changing parse behavior (#1258).
  • Overridable Markdown templates. MarkdownRenderer::with_template and the usage generate markdown --template NAME=PATH flag replace individual bundled Tera templates while unchanged ones remain available via {% include %} (#1267).

Changed

  • Compact Markdown references by default. Generated Markdown now uses MarkdownTheme::Compact — dense grouped lists instead of one heading per argument or flag, with title-cased metadata labels, "Output Formats" instead of "Output", and long output catalogs collapsed behind <details>. The previous layout is MarkdownTheme::Detailed (#1272, #1280).
  • Redesigned command lists on -h and --help. Rows now show one aligned column of leaf names plus a short summary; usage syntax and children's full long_help stay on their own pages. mise's root --help drops from hundreds of lines to 136 (#1284).
  • Short help wraps. Descriptions and annotations like [env: …] no longer run off the terminal on -h; they join first and wrap into the description column together, matching what --help has always done (#1287).
  • Long-help annotations align to the description column. [possible values: …], (default: …), and env notes now sit under the description they qualify instead of at a fixed four-space indent (#1291).

Fixed

  • Attached completion values. --format=j now completes as --format=json — static choices, named completers, and runtime overlays route through the attached-value context. Generated specs also materialize the parser-supplied help/version spellings as builtin=#true flags so listings and completions see them (#1277).
  • Flattened command metadata. Outputs, select, and exit codes declared on flattened Args types survive spec emission (including nested flatten) (#1268).
  • Typed defaults with restricted choices. Choice validation now runs only on values from argv or environment variables, so a default_fn may return an empty or non-advertised typed value (#1269).
  • Override does not erase an invalid choice. mise --log-level=v --trace used to be accepted by usage-argv (and usage-go) because the post-binding choice check sat inside the given guard that overrides clears. Both parsers now judge a displaced flag's leftover choice like usage-lib and clap do; Go exports a matching CheckDisplaced (#1286).
  • KDL writers agree on three more nodes. write_group quotes dashed members ("--allow" not --allow), cmd writes help_heading before help, and root before_help/after_help move earlier and into before-then-after order. A maximal fixture now covers every node both writers emit (#1289).
  • Generated partial fields no longer trip Clippy. #[expect(clippy::pub_underscore_fields)] on Partial structs keeps internal fields public for cross-module flattening without noisy adopter lints (#1278).
  • Nushell completion. Replaces deprecated str downcase usage on Windows so case-insensitive command matching keeps working (#1262 by @TheBearodactyl).

Performance

  • Skip empty admonition contexts in Markdown rendering, clawing back most of the cost added by note/warning blocks (#1279).
  • Reduce sort code size in the argv hot path (#1264).

New Contributors

💚 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.

Check out latest releases or
releases around jdx/usage v6.2.0

Don't miss a new usage release

NewReleases is sending notifications on new releases.

Get notifications