jdx/usage v6.5.0

v6.5.0: Sigils, clauses, and Cobra examples

on GitHub

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