jdx/usage v3.5.0

v3.5.0: Type-Safe SDKs and Zsh Colon Fixes

on GitHub

This release introduces usage generate sdk — type-safe subprocess-wrapper SDKs for TypeScript and Python derived from a usage spec — and fixes two zsh completion bugs around colons in subcommand and value names that were biting mise users.

Added

• usage generate sdk for TypeScript and Python (#623 by @gaojunran). A new generator emits a type-safe SDK client for any usage-described CLI. The SDK is a subprocess wrapper — not a native binding — so it works for any binary on $PATH, with typed args, flags, and choice-constrained values instead of stringly-typed subprocess.run/spawn calls.

  usage generate sdk -l typescript -o ./sdk -f ./mycli.usage.kdl
  usage generate sdk -l python     -o ./sdk -f ./mycli.usage.kdl

  import { Mycli } from "./sdk";
  const cli = new Mycli();
  const result = await cli.build.exec(
    { target: "release", output: "./dist" },
    { release: true },
  );

  Each generated SDK has three pieces: a types module (dataclasses / interfaces, with Literal / union types for choices and global flags propagated to every subcommand), a client module mirroring the subcommand tree with exec() methods that build the argv list, and a small runtime module wrapping subprocess.run / child_process.spawn. See the SDK generation guide for the full walkthrough. Rust support is planned.

• usage sponsors command and docs sponsor block (#662, #608, #656). The new top-level usage sponsors command and a sponsor strip on the docs site acknowledge 37signals and link to the canonical en.dev sponsor pages. A dedicated /sponsors docs page lists tiers fetched live from en.dev/sponsors.json.

• More CLI-framework integration guides (#655, #667 by @gaojunran). The docs now cover using usage alongside JCommander, picocli, and Clikt (Java/Kotlin) and urfave/cli and Kong (Go), joining the earlier Commander.js / oclif / yargs / Typer / Click guides.

Fixed

• zsh: all subcommands with a shared colon prefix now show up in completion (#666 by @zeitlinger). _describe groups matches that share a \:-escaped prefix and surfaces only one entry per group, so a spec with release:create, release:docs-sync, release:pr, and release:update would only ever show release:create in the menu. The completion now builds its own display column and calls compadd directly so every match is offered, with descriptions padded for column alignment. Regenerate zsh completions to pick up the fix. Surfaced via jdx/mise tasks.

• zsh: completion no longer truncates values at the first colon (#670 by @davidolrik). Completing a mise task named chezmoi:brew:dump was inserting chezmoi and then destroying the user's typed :brew: on the next <Tab>, because _describe parses candidate:description in both the display and insert arrays it receives. The fix escapes colons in the insert column the same way the display column was already escaped. Regenerate zsh completions to pick up the fix.

• parse: orphan short/long aliases on a re-declared global flag are preserved (#659 by @JamBalaya56562). Follow-up to #649. When a subcommand re-declared an inherited global flag as non-global and added a new alias (e.g. mise's run/tasks run re-declaring long-only --raw/--silent as -r --raw / -S --silent), the merge kept the global flag but discarded the re-declaration wholesale, throwing away the new short. The parser now unions the re-declaration's extra short/long aliases (matched on a shared long name) onto the surviving global flag, so completions like mycli run -r sample:run -- <TAB> work and usage_raw=true reaches as_env() and mount scripts. This makes mise's promote_orphan_shorts workaround unnecessary.

Changed

• Docs examples use KDLv2 raw multiline strings throughout (#657 by @salim-b). The remaining KDLv1 r#"…"# raw strings in the documentation and examples/mise.usage.kdl were converted to KDLv2 #"""…"""#, matching the rest of the docs that already use KDLv2 syntax (#true, etc.).

New Contributors

• @zeitlinger made their first contribution in #666
• @davidolrik made their first contribution in #670
• @salim-b made their first contribution in #657

Full Changelog: v3.4.0...v3.5.0

💚 Sponsor usage

usage is built by @jdx at en.dev — an independent developer-tooling studio behind 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 en.dev. Every sponsorship helps the project stay independent and moving.