jdx/usage v6.3.0

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

on GitHub

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