jdx/usage v3.3.0

v3.3.0: Auto-completion for usage shebang scripts

on GitHub

The headline feature in this release is one-line auto-completion for usage-shebang scripts: source a single init script from your shell rc and every usage-powered script on your $PATH gets <Tab> completion automatically. This release also brings new third-party integration guides and a handful of docs site polish fixes.

Added

• Auto-completion for usage shebang scripts (#620 by @jdx). A new usage generate completion-init <shell> subcommand (alias ci) emits a one-time init script for bash, zsh, and fish. Source it once and any executable on $PATH whose first line is a usage shebang gains tab-completion — no per-script usage g completion <shell> <bin> -f <script> generation step.

  # bash — add to ~/.bashrc (source after bash-completion)
  source <(usage g completion-init bash)
  
  # zsh — add to ~/.zshrc
  source <(usage g completion-init zsh)
  
  # fish — add to ~/.config/fish/conf.d/usage.fish
  usage g completion-init fish | source

  Mechanism per shell:

  • bash registers a complete -D default handler that peeks the candidate command's first line for a usage shebang and dispatches to usage complete-word. Non-usage commands chain to bash-completion's _completion_loader, so existing completions keep working.
  • zsh registers a compdef -default- fallback with the same shebang detection, falling back to _files for non-usage commands.
  • fish has no default-completer fallback, so the init scans $PATH once at shell startup and registers complete -c <name> for each shebang script it finds.

  Pass --usage-bin (or set JDX_USAGE_BIN) if your usage binary is installed under a different name.

• Third-party integration guides. Documentation now covers using usage alongside Commander.js, oclif, and yargs (#616 by @gaojunran) as well as Typer and Click (#619 by @gaojunran), based on the usage-integrations monorepo.

Fixed

• Docs site banner now stacks vertically on viewports <=640px with the close button pinned to the top-right corner, fixing cramped two-line wrapping on mobile (#603 by @jdx).

Full Changelog: v3.2.1...v3.3.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.