jdx/usage v6.7.0

v6.7.0: Semantic command styling and sharper CLI docs

on GitHub

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