build(deps): update dependency jdx/usage to v6 by renovate[bot] · Pull Request #309 · diggsweden/devbase-core

renovate · 2026-09-15T15:42:33Z

ℹ️ Note

This PR body was truncated due to platform limits.

This PR contains the following updates:

Package	Update	Change	Pending	OpenSSF
jdx/usage	major	`v5.1.0` → `v6.9.0`	`v6.10.0` (+1)

Warning

Some dependencies could not be looked up. Check the Dependency Dashboard for more information.

Release Notes

jdx/usage (jdx/usage)

`v6.9.0`: : Default-subcommand flag routing, standalone Args parsing, and smaller help builds

Compare Source

Flags belonging to a default subcommand can now select it without typing its name, a derived Args type can be parsed on its own, help colours can be remapped, and a series of help-rendering changes trims binary size for usage-rs adopters. Bash completion also stops mangling colon-separated candidates.

Added

(parse) Opt-in default-subcommand flag routing (#1413, @jdx). With default_subcommand_flags, leading flags that belong only to the configured default subcommand route to it, so em -ua @world parses as em install -ua @world. Explicit command names and aliases still win, parent-only flags and bare invocations stay on the parent, a mixed short bundle such as -pua keeps the parent's -p, and -- or an unknown flag stops the lookahead. Completion also offers the default command's flags at the root. Supported in KDL specs, the Rust derive, and the Go runtime; existing routing is unchanged without the opt-in. usage lint reports default_subcommand_flags declared without a default_subcommand.
```
default_subcommand "install"
default_subcommand_flags #true
```
```
#[usage(default_subcommand = "install", default_subcommand_flags)]
```
(parse) Parse a derived Args type without an enclosing CLI (#1419, @jdx). usage::parse_args_from::<T> treats the slice as that command's words; usage::parse_args_from_argv::<T> strips argv0 first. Both reuse the command's compiled flags, positionals, defaults, validation, and nested subcommands, and return the ordinary parse errors, including help and version requests. Available behind the spec feature.
```
let install = usage::parse_args_from::<Install>(&args)?;
```
(help) Remap semantic help colours with a Palette (#1414, @lu-zero). The heading, option, metavar, and command roles were previously fixed SGR colours. help::Palette remaps any of them using the existing {$…} tag vocabulary (for example "cyan+bold"), and Style::palette applies it; role names expand once, so mapping metavar to "heading" uses the built-in heading colour. Hosts that own the exit path get embedded_outcome_paletted / embedded_outcome_into_paletted (and embedded::outcome_paletted); parse() and plain rendering are unchanged.
```
let palette = usage::help::Palette::DEFAULT.metavar("cyan+bold");
match Ex::embedded_outcome_paletted(&argv, palette) { /* … */ }
```

Changed

(cli) Smaller binaries and faster help rendering (#1396, #1399, #1400, #1401, @jdx). Help sorting and rendering do less work and share more code, plain (uncoloured) help skips colour-span analysis, and the flag diagnostics share one formatter. Help output is byte-identical; on the oxc binaries used for measurement this removed roughly 360 KiB combined, and plain --help rendered about 18% faster locally. Two new opt-ins let CLIs trim further:
- Flattened subcommand pages, HelpAll, and recursive render_all now live behind a help-advanced feature (enabled by default in usage-rs and usage-argv). A CLI that uses none of them can disable defaults and omit it:
```
usage = { package = "usage-rs", version = "6", default-features = false, features = ["help", "diagnostics", "completions"] }
```
- #[usage(spec_endpoint_file = "cli.usage.kdl")] answers __usage_spec__ from a KDL file included at compile time, keeping the endpoint without linking the runtime serializer. to_kdl() still generates from live metadata, so regenerate the file after CLI changes and test the two for drift.
Compatibility note: dependents that already set default-features = false and declare flatten_help or a HelpAll flag must add help-advanced; the derive now rejects those declarations at compile time, and hand-written metadata requesting advanced help panics when rendered instead of being silently ignored.

Fixed

(bash) Preserve colon-prefixed completion words (#1405, @jdx). When : is in COMP_WORDBREAKS, Readline replaces only the fragment after the last colon, so candidates such as update:deps:no-cooldown were inserted with a duplicated update:deps: prefix. The generated Bash script now forwards the current Readline word and COMP_WORDBREAKS to the __complete_word__ request, and the binary reports the prefix Readline keeps so the script can trim it; escaped colons, consecutive colons, and a cursor on a colon are handled. Path candidates are unaffected. Regenerate Bash completion scripts to pick up the fix (reported in jdx/mise#12970).

New Contributors

@lu-zero made their first contribution in #1414

Full Changelog: jdx/usage@v6.8.0...v6.9.0

💚 Sponsor usage

usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

`v6.8.0`: : Native completions and sharper docs output

Compare Source

This release gives the usage CLI native shell completions (including PowerShell), adds a configurable link extension for Markdown docs, and fixes a batch of synopsis and Markdown rendering issues across docs and man pages.

Added

(cli) Native shell completions (#1388, @jdx). usage --completions <shell> now emits native scripts that call the installed binary's compiled completion handler instead of caching a spec and relying on the bash-completion helpers. Bash, Zsh, Fish, and a new PowerShell script are all supported, and scripts use command usage so a shell function or alias can no longer shadow the executable. All four scripts are published alongside the CLI spec as signed Packslip resources. General usage generate completion behavior is unchanged.
(docs) Configurable Markdown link extension (#1394, @jdx). Generated Markdown links previously always ended in .md, forcing consumers who serve HTML or extensionless pages to rewrite links after generation. A new --link-extension flag (and MarkdownRenderer::with_link_extension, default .md) controls the suffix on command and configuration links without changing output filenames:
```
usage generate markdown --file mycli.usage.kdl --link-extension .html
```
Custom templates now also receive link_extension and config_link in their context.

Fixed

(docs) Render optional subcommands and mount synopses (#1393, @jdx). Generated synopses showed <SUBCOMMAND> even when a command could run without one; the shared usage string now honors subcommand_required (using [SUBCOMMAND] when optional) and custom placeholder names, keeping terminal help, Markdown, man pages, JSON, and SDK docs consistent. Unresolved mounts can also declare a display-only synopsis (for example mount run="mycli tasks --usage" synopsis="[TASK] [ARGS]…") to document dynamic arguments without running discovery; parsing and completion are unchanged.
(docs) Preserve Markdown code blocks and headings (#1392, @jdx). Indented help text was converted to code fences by stripping four spaces from every matching line, which could corrupt nested lists and existing fenced examples. Markdown code-block boundaries are now parsed so only real indented code blocks are converted, fences are chosen longer than any embedded backtick runs, and HTML escaping recognizes longer fences. Hidden subcommands are now filtered out before the Subcommands heading, and the duplicate synopsis line was removed from the multipage index.
(manpage) Render mount synopses and custom command names (#1395, @jdx). Completes the man-page side of the synopsis fixes above. The man-page renderer now carries declarative mount synopses and custom subcommand names into its own synopsis (instead of hard-coded <COMMAND>/[COMMAND]), includes mount fragments in root and subcommand synopses without running discovery, and emits a detail section for a command whose only documentation is a mount synopsis.

Changed

(docs) Refreshed guides, navigation, and landing page (#1391, @jdx). A new getting-started guide walks from install through KDL, lint/explain, docs/man, completions, and diff. Navigation is reorganized into guides, framework docs, and references with route-specific sidebars; the landing page is simplified with clearer starting points for Rust apps, existing CLIs, and scripts. Installation commands, Rust and SDK examples, and completion setup were corrected, Go is now labeled a development preview, and broken links across all 171 Markdown files were fixed.

Full Changelog: jdx/usage@v6.7.1...v6.8.0

💚 Sponsor usage

usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

`v6.7.1`: : macOS Release Build Fix

Compare Source

This is a small maintenance release with no user-facing changes. It fixes the release automation and macOS build pipeline so that v6.7.1 could be published; there are no library, CLI behavior, or output changes for end users.

Changed

(release) Bypass mbx for universal macOS release builds (#1385, @jdx). The universal macOS build failed because mbx 1.8.1 rejects Cargo invocations that pass both Apple architecture targets at once. MBX_DISABLE is now set for the universal target so Cargo runs directly; other release targets are unaffected.
(release) Allow empty commits to trigger release PRs (#1386, @jdx). Release automation no longer restricts git-cliff to crate paths, so version bumps and changelog entries now account for all qualifying commits in the release range, including workflow-only fixes.

Full Changelog: jdx/usage@v6.7.0...v6.7.1

💚 Sponsor usage

usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

`v6.7.0`: : Semantic command styling and sharper CLI docs

Compare Source

This release adds a new semantic style for subcommand names in help output, fixes several help and parsing edge cases, and notarizes the macOS binary so browser downloads pass Gatekeeper.

Added

(help) Semantic command styling (#1375, @jdx). Colored help now highlights subcommand names and the built-in help row with a new command semantic style (bold green by default), matching the palette family used for options. Plain output is unchanged, so stripping ANSI still yields byte-identical pages. The {$command}…{/$} tag is now recognized across the derive, KDL, Go, and shared help-template vocabularies alongside heading, option, and metavar.

Fixed

(cli) Show help for a bare exec command (#1361, @jdx). usage exec --help (and the x alias, with -h or --help) now prints the exec command page instead of failing with a missing <COMMAND> error. Fully specified invocations like usage exec <COMMAND> <BIN> --help still route help to the wrapped script as before.
(parse) Report the next implicit clause argument (#1372, @3w36zj6). When a partial parse of a bare command with an implicit clause stopped, the parser incorrectly returned no next argument, so completion could not offer that argument's choices or invoke its custom completer. The stopping position is now resolved through the active argument set, restoring completions for clause commands.
(docs) Make --indented-blocks-to-code-fences work on single-file markdown (#1367, @jdx). The flag that converts four-space indented blocks into code fences was a no-op for single-file usage generate markdown output because the model was rendered before the option was applied; it now takes effect. The flag was also renamed from the misleading --replace-pre-with-code-fences (kept as a hidden alias for compatibility).

Changed

(docs) Rewrote CLI help text and guide pages (#1364, @jdx). Since help text is the source for reference pages, man pages, and completions, this corrects and expands it: --usage-cmd no longer documents a nonexistent default, <SCRIPT> and --shell now have help, per-shell commands explain that -h/--help print the wrapped script's page, and commands like lint, mcp, generate completion, and the root command gained long help. The CLI guide pages were rewritten around task-to-command tables. Adopters with snapshot tests over usage's help output will see diffs.
(release) Notarize the macOS binary (#1378, @jdx). Release macOS binaries are now signed with the hardened runtime and submitted to Apple's notary service, so archives downloaded through a browser no longer hit the "cannot be verified" Gatekeeper dialog.

New Contributors

@3w36zj6 made their first contribution in #1372

Full Changelog: jdx/usage@v6.6.1...v6.7.0

💚 Sponsor usage

usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

`v6.6.1`: : Cleaner plain help and smarter flag completion

Compare Source

A small bugfix release focused on help rendering and shell completion. Plain help output no longer leaks embedded ANSI escapes, root-only help metadata stays on the root page, and completion now handles attached --flag=value syntax.

Fixed

(complete) Complete attached long flag values (#1349, @nfvelten). Completions now work for inline long-option syntax like --flag=value: the fragment after = is used to narrow suggested values, the full --flag= prefix is reattached to each candidate (since shells replace the whole word), and file-path fallback still applies when a flag has no explicit choices. Fixes #999.
(docs) Strip authored ANSI from plain help (#1357, @jdx). Style::PLAIN now removes ANSI CSI/SGR sequences that were already baked into command metadata (common when migrating from clap's color_print::cstr! help), keeping plain terminal help and generated Markdown escape-free while colored output is unchanged.
(help) Keep root help on the root page (#1358, @jdx). Before/after help, examples, author, and license are now command-local instead of falling back to the root spec. Root-specific material no longer appears on unrelated leaf commands (e.g. mise self-update --help), aligning with clap's command-local help behavior. Applied consistently across the Rust renderer, documentation templates, and the Go renderer.

New Contributors

@nfvelten made their first contribution in #1349

Full Changelog: jdx/usage@v6.6.0...v6.6.1

💚 Sponsor usage

usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.

`v6.6.0`: : Scoped flags and implicit clauses

Compare Source

This small release extends the repeatable clause groups introduced in v6.5.0 with per-instance scoped flags and separator-free (implicit) clauses, and completes their integration across the compiled parser, portable KDL, help, completions, and generated documentation.

Added

Scoped flags and implicit clauses. Clauses can now carry flag nodes that are scoped to a single repeatable instance and reset at each boundary. The separator is now optional: when omitted, a clause with exactly one required, non-variadic positional ends each instance implicitly as soon as that terminal positional is consumed. Scoped flags precede and apply to the next terminal positional, and the parser rejects ambiguous implicit layouts, conflicting flag spellings, duplicate scalar flags within an instance, and trailing scoped flags that never complete an instance. Threaded through the interpreted parser, the compiled argv parser, Rust derive, portable KDL emission, help/completion, usage diff, and the generated Go bindings (#1343, @jdx). Requires min_usage_version "6.6".
```
clause "tools" {
  flag "--postinstall <COMMAND>"
  arg "<tool>"
}
```
use --postinstall A a --postinstall B b produces two tools instances: postinstall="A", tool="a" and postinstall="B", tool="b". In Rust derive, omit separator and place the scoped fields on the nested Args type.

Fixed

Complete implicit clause integration (#1345, @jdx):
- Command-level relationships (requires, conflicts, etc.) can now target arguments inside typed clauses in the compiled parser, so e.g. --force can require a clause's terminal positional.
- Portable KDL now emits spec-facing argument names (e.g. TOOL, --postinstall) for clause relationship fields instead of Rust field selectors, keeping reference-parser round-trips valid.
- Repeated clauses are now rendered as optional groups (wrapped in […]) in compiled help, manpage synopsis, and Markdown, and clause-scoped flags and arguments now appear in generated documentation. Empty clauses no longer fail to render.

Full Changelog: jdx/usage@v6.5.0...v6.6.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.

`v6.5.0`: : Sigils, clauses, and Cobra examples

Compare Source

This release introduces two new positional-argument primitives — sigil-classified arguments and repeatable clause groups — plus support for Cobra's Example field when generating specs, and a zsh completion fix for aliases.

Added

Sigil-classified positional arguments. Positionals can now be declared with a leading sigil prefix so they are matched by that prefix rather than by slot order. The prefix is treated as syntax and stripped before the value is stored, validated, or completed, and a sigil argument never advances the ordinary positional cursor — so classified values can interleave with flags and normal positionals. Completion, canonical KDL, argv tables, derive metadata, the Python/TypeScript SDKs, and the conformance corpus all carry sigils through the same contract, and tab completion strips/restores the prefix on every candidate (#1322, #1319, @jdx). Requires min_usage_version "6.5".
```
arg "[tool]..." sigil="+" {
  choices "node@22" "node@24" "python@3.14"
}
arg "<command>"
arg "[args]..."
```
With that spec, ex +node@24 node -v binds tool=["node@24"], command="node", and args=["-v"]. In Rust derive, annotate the field with #[usage(sigil = "+")].
Repeatable clause groups. A command can declare one separator-delimited group of positionals that repeats: each separator ends the current instance and starts a new one instead of overwriting it, and every instance is stored independently in parse output. Flag and positional state reset at each boundary, an explicit -- protects a literal separator, and completion treats the separator like a restart. Clauses are wired through the interpreted parser, the zero-allocation compiled argv parser, Rust derive (#[usage(clause, separator = "…")] on Vec<T>), the Go parser, and usage diff (which reports clause add/remove/separator changes as breaking) (#1321, #1320, @jdx). Requires min_usage_version "6.6".
```
clause "tasks" separator=":::" {
  arg "<task>"
  arg "[args]..." var=#true double_dash="automatic"
}
```
run lint --fix ::: test --all produces two tasks instances: task="lint", args=["--fix"] and task="test", args=["--all"].
Cobra Example field support. Specs generated with --usage-spec now include Cobra's Example text as example nodes — a root command's example becomes a top-level node, and a subcommand's becomes a child of its cmd block. The conventional two-space indent is stripped while multiline formatting and comment lines are preserved (#1333, @thecodesmith).

Fixed

(zsh) Command-position aliases are now expanded before the line is sent to the completion binary, so completions work for aliases that add arguments (e.g. gfin="mise run git:finish-branch"). Recursive and cyclic aliases are handled safely (#1330, @halms).

Changed

The Rust framework (usage-rs) documentation and site no longer carry the experimental label; usage-cli itself is built with it. The separate usage-dynamic crate remains marked experimental, and Go remains a work in progress (#1334, @jdx).

New Contributors

@halms made their first contribution in #1330
@thecodesmith made their first contribution in #1333

Full Changelog: jdx/usage@v6.4.1...v6.5.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.

`v6.4.1`: : Colorful Help and Sharper Negative-Value Parsing

Compare Source

A focused patch release that adds terminal-aware color to interpreted help output, tightens how negative numbers are parsed as flag values, and lowers the published crates' minimum supported Rust version.

Added

Colorized help output. The usage CLI, usage bash, and usage exec now render interpreted help with terminal-aware semantic styling (headings, options, metavars, inline markdown, and help_template {$…} tags). Coloring is auto-detected from the terminal and honors NO_COLOR and CLICOLOR_FORCE; plain rendering remains available for snapshots and generated artifacts (#1309, @jdx).

Fixed

More predictable negative-value parsing. Tokens like -1 are only consumed as a detached flag value when allow_negative_numbers is set or when the flag's value is truly required (no default_missing, not optional). This keeps optional and default_missing flags from swallowing negative numbers during subcommand and external_subcommand discovery, while required flags and explicit opt-ins still bind them correctly. Missing-value errors are also now reported for the awaiting flag even when another recognized option follows (#1317, #1318, @jdx).
Hidden commands excluded from Markdown docs. Single-file Markdown reference generation no longer emits sections for commands marked hide=#true, matching the existing index and flag/arg filtering (#1315, @jdx).
Simplified the required_unless predicate logic for arguments and flags with no change in behavior (#1326, @jdx).

Changed

Lowered MSRV to Rust 1.91. The published usage-lib, usage-dynamic, clap_usage, and usage-cli crates now build on Rust 1.91 (down from 1.95), letting usage-cli install on runner images that ship Rust 1.94 (#1314, @jdx).

Dependency Updates

Updated winnow to v1 (#1313, @renovate[bot]).

Full Changelog: jdx/usage@v6.4.0...v6.4.1

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

`v6.4.0`: : XDG config layers and terminal-aware help wrapping

Compare Source

This release adds XDG-based config file resolution, teaches --help to wrap to the terminal width with a smarter column layout, fixes zsh completions at mid-line cursor positions, and slims down the library's dependency tree with an independent Markdown feature.

Added

XDG file layers for config resolution. FileLayer::xdg(XdgBase, path) resolves a relative path under the standard XDG config, data, state, cache, or runtime bases, honoring each base's defaults, absolute-path rules, and precedence with no new dependencies. Config and data bases include system search directories (with the user file winning), while state, cache, and runtime stay user-scoped. The Config derive gains matching #[usage(file(path = "…", xdg = "config"))] metadata that expands into the standard precedence chain in the emitted spec (#1303, @jdx).
```
use usage::config::{FileLayer, XdgBase};

// Reads $XDG_CONFIG_HOME then $XDG_CONFIG_DIRS in precedence order,
// falling back to $HOME/.config and /etc/xdg when unset.
let layer = FileLayer::xdg(XdgBase::Config, "ex/config.toml");
```

Fixed

Terminal help now wraps to the terminal width. Help output uses a hybrid column layout: long option spellings keep their description inline when at least 30 columns remain, otherwise the prose stacks under the shared description column. Paragraphs, section intros, annotations, bullet and numbered lists (with hanging indents), and labelled notes/warnings all wrap, while blank lines and preformatted (4-space/tab-indented) lines are preserved. The Rust reference renderer, the dependency-free usage-argv renderer, and the generated Go renderer stay in parity (#1304, @jdx).
zsh completions respect the cursor position. Generated zsh scripts now forward zsh's one-based CURRENT to complete-word as a zero-based --cword, so completing a word in the middle of a command line (for example --f before a trailing argument) resolves against the correct word instead of the last one (#1300, @jdx, fixes #1298).

Changed

Independent markdown and manpage doc features. Markdown and manpage rendering are now separate features so consumers who only generate Markdown can drop the roff dependency. The existing docs and roff feature names remain as aliases. Internally, heck, shell-words, and strum were replaced with focused in-tree implementations and unicode-width was bumped to 0.2, shrinking the dependency footprint while keeping the public API and error variants stable (#1301, @jdx).
```
usage-lib = { version = "6", default-features = false, features = ["markdown"] }
```

Full Changelog: jdx/usage@v6.3.0...v6.4.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.

`v6.3.0`: : Colorful help by default and a slimmer dependency tree

Compare Source

This release brings semantic colors to --help output by default, adds a runtime style vocabulary for help_template, tightens help-column layout, and removes the kdl and default miette dependencies from the library.

Added

Semantic colors in help output by default. Coloured --help now renders headings, option literals, and metavariables with distinct semantic colors so pages are easier to scan, while plain and piped output stays untouched (#1297, @jdx).
Runtime style tags in help_template. Templates can now colour and emphasize their own prose with a dependency-free tag vocabulary of 23 named styles (heading, option, metavar, the 8 standard and 8 bright ANSI colors, plus bold, dim, italic, underline). Styles nest and combine, {$$…}/{/$$} escape a literal tag, and substituted section text stays opaque so prose containing {$red} is left alone. Malformed markup falls back safely instead of panicking, and the vocabulary is validated in both Rust derives and KDL specs (#1297, @jdx).
```
help_template = "{$heading}MY TOOL{/$}\n\n{{usage}}\n\n{$cyan}{{flags}}{/$}"
```
Optional miette feature. With the library's own error rendering now built in, an opt-in miette feature makes UsageErr and KDL parse diagnostics implement miette::Diagnostic again, preserving source spans, labels, severity, and help text for callers that already use a miette reporter (#1296, @jdx).

Fixed

Long entries no longer widen the whole help table. The aligned usage column is now capped at 40% of the remaining width, so a single long flag, argument, or command name (for example --report-unused-disable-directives-severity <SEVERITY>) no longer forces every entry on the page into block layout. Oversized entries drop into a wrapped block under their own spelling while shorter neighbors keep a readable two-column layout. Applied consistently across the reference, zero-allocation, and Go renderers (#1293, @jdx).
Repeatability ellipses removed from output. The … marker is no longer appended to repeatable flags in help tables, Usage: synopses, Markdown, or generated SDK docs, so options render with ordinary spellings like --env <ENV>. Value-side ellipses (<arg>…) are unchanged, and repeatability is still preserved structurally in the spec via var (#1295, @jdx).
Go renderer now prints section prose. The Go help renderer honours the headings prose field introduced in v6.2.0, so a generated Go CLI renders the same declared section text as the Rust renderer instead of printing the heading alone (#1290, @jdx).

Changed

kdl and default miette dependencies removed. usage-lib now vendors a trimmed KDL v2 parser and renders diagnostics (source labels, help, and codes) with a small in-process renderer, dropping two dependencies from the default build without changing spec parsing behaviour. Apache-2.0 notices for the vendored code are recorded in NOTICE.md (#1296, @jdx).

Breaking Changes

UsageErr no longer derives miette::Diagnostic by default. Callers who relied on miette integration should enable the new miette feature to restore it (#1296).
SpecFlag::usage() no longer round-trips the repeatability marker: parsing --flag… still sets var, but reprinting yields --flag. Keep var=#true as the source of truth in specs rather than relying on the … suffix surviving a reparse (#1295).

Full Changelog: jdx/usage@v6.2.0...v6.3.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.

`v6.2.0`: : Embedded parsing, richer specs, and a redesigned help page

Compare Source

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

@TheBearodactyl made their first contribution in #1262

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

`v6.1.1`: : Windows path fixes and slimmer derived binaries

Compare Source

A patch release focused on making usage a good citizen on Windows and shrinking the code the derive macro generates. Five separator- and prefix-aware fixes across complete, config and argv land alongside two derive perf passes that trim ~16.5% off a mise-scale stripped binary.

Fixed

Path completion keeps the separator you typed. complete_path already accepted / or \ on Windows on the way in, but wrote back the platform separator for the middle of the path and a hard-coded / for the trailing directory marker, so typing target/de/inc came back as target\debug\incremental/ — a spelling no shell will match. Output now uses the same separator the token already contains (#1230 by @JamBalaya56562).
Config paths lose the verbatim prefix. normalize still canonicalizes for boundary checks, but strips the Windows \\?\ / UNC extended-length prefix before returning, so FileLayer::paths — which config explain reports as provenance — matches what a caller built with current_dir().join(…) (#1232 by @JamBalaya56562).
Install plans respect the target platform. plan takes a Platform for a reason: an install plan is made for a machine, not on one. Three places had regressed to using the host's separator (and Path::is_absolute / Path::ends_with in tests) — a Linux plan made on Windows was emitting fpath+=('/home/u\.local\share\zsh\site-functions'). All fixed to route through Platform::separator and the crate's own platform-aware helpers (#1233 by @JamBalaya56562).
Simpler completion-script headers. Rust and Go generators now emit a single @generated by … marker line instead of the extra "do not edit / no cached spec" preamble (#1226 by @jdx).
Cleaner flag reference docs. Generated Markdown headings show only the canonical short and long form; additional visible spellings move to a dedicated Aliases line. Hidden-alias filtering and interactive help are unchanged (#1228 by @jdx).

Performance

Two stacked derive-macro passes shrink the code every generated build() carries, without changing behavior or error messages:

Cold error construction moves out of line into four #[cold] #[inline(never)] builders in usage-argv (invalid_utf8_value, invalid_parsed_value, invalid_choice_value, invalid_os_value). On a mise-sized shadow binary this drops the stripped size from 1,579 KB to 1,369 KB (−210 KB, −13.3%) and roughly halves generated build() code. Cold parse instructions dip 0.9%; wall time is unchanged within noise (#1235 by @jdx).
Repeated-value collection loops are shared through four monomorphized helpers (utf8_values, parsed_values, os_values, spec::choice_values) with an inlined is_empty() fast path that avoids paying for a call when a Vec-shaped field received nothing. Another −51 KB on top, for a cumulative −261 KB (−16.5%) across the stack; instruction counts end up below the pre-stack baseline (#1236 by @jdx).

Tests

Joined Windows test paths component-by-component so a self-comparison stops disagreeing with itself, and scoped the "refuse to skip under CI" guard for zsh/fish/bash-completion to Unix — Git for Windows does not ship bash-completion, and the workflow does not install POSIX shells on Windows either (#1229 by @JamBalaya56562).
Silenced two Windows-only warnings (unused import: WarningKind, enum_variant_names on Shell::PowerShell) so cargo clippy --all-targets -- -D warnings passes there (#1234 by @JamBalaya56562).

Between them, these three test PRs take a windows-latest cargo test --all --all-features run from 2,383 pass / 5 fail to 2,393 pass / 0 fail, clearing the way for a real Windows CI job.

Full Changelog: jdx/usage@v6.1.0...v6.1.1

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

❗ Important

✂ PR body was truncated to here.

Configuration

📅 Schedule: (in timezone Europe/Stockholm)

Branch creation
- "after 8:00pm on Saturday,before 11:59pm on Sunday"
Automerge
- At any time (no schedule defined)

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR is behind base branch, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

If you want to rebase/retry this PR, check this box

This PR was generated by Mend Renovate. View the repository job log.

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

renovate Bot added the dependencies Related to project dependencies label Sep 15, 2026

renovate Bot requested a review from a team as a code owner September 15, 2026 15:42

build(deps): update dependency jdx/usage to v6

c22fc08

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

renovate Bot force-pushed the renovate/jdx-usage-6.x branch from da593c1 to c22fc08 Compare September 19, 2026 17:16

Navigation Menu

build(deps): update dependency jdx/usage to v6 - #309

build(deps): update dependency jdx/usage to v6#309
renovate[bot] wants to merge 1 commit into
mainfrom
renovate/jdx-usage-6.x

renovate Bot commented Sep 15, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

Conversation

renovate Bot commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release Notes

v6.9.0: : Default-subcommand flag routing, standalone Args parsing, and smaller help builds

Added

Changed

Fixed

New Contributors

💚 Sponsor usage

v6.8.0: : Native completions and sharper docs output

Added

Fixed

Changed

💚 Sponsor usage

v6.7.1: : macOS Release Build Fix

Changed

💚 Sponsor usage

v6.7.0: : Semantic command styling and sharper CLI docs

Added

Fixed

Changed

New Contributors

💚 Sponsor usage

v6.6.1: : Cleaner plain help and smarter flag completion

Fixed

New Contributors

💚 Sponsor usage

v6.6.0: : Scoped flags and implicit clauses

Added

Fixed

💚 Sponsor usage

v6.5.0: : Sigils, clauses, and Cobra examples

Added

Fixed

Changed

New Contributors

💚 Sponsor usage

v6.4.1: : Colorful Help and Sharper Negative-Value Parsing

Added

Fixed

Changed

Dependency Updates

💚 Sponsor usage

v6.4.0: : XDG config layers and terminal-aware help wrapping

Added

Fixed

Changed

💚 Sponsor usage

v6.3.0: : Colorful help by default and a slimmer dependency tree

Added

Fixed

Changed

Breaking Changes

💚 Sponsor usage

v6.2.0: : Embedded parsing, richer specs, and a redesigned help page

Added

Changed

Fixed

Performance

New Contributors

💚 Sponsor usage

v6.1.1: : Windows path fixes and slimmer derived binaries

Fixed

Performance

Tests

💚 Sponsor usage

Configuration

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

renovate Bot commented Sep 15, 2026 •

edited

Loading

`v6.9.0`: : Default-subcommand flag routing, standalone Args parsing, and smaller help builds

`v6.8.0`: : Native completions and sharper docs output

`v6.7.1`: : macOS Release Build Fix

`v6.7.0`: : Semantic command styling and sharper CLI docs

`v6.6.1`: : Cleaner plain help and smarter flag completion

`v6.6.0`: : Scoped flags and implicit clauses

`v6.5.0`: : Sigils, clauses, and Cobra examples

`v6.4.1`: : Colorful Help and Sharper Negative-Value Parsing

`v6.4.0`: : XDG config layers and terminal-aware help wrapping

`v6.3.0`: : Colorful help by default and a slimmer dependency tree

`v6.2.0`: : Embedded parsing, richer specs, and a redesigned help page

`v6.1.1`: : Windows path fixes and slimmer derived binaries