Usage CLI

usage is the command-line utility around the usage spec. A spec describes a CLI's commands, flags, and arguments once, in KDL. This tool turns that one description into the things a CLI ships with, and runs scripts that carry a spec in their own comments.

To get	Run	Guide
Tab completion for bash, zsh, fish, PowerShell, and Nushell	usage generate completion	Completions
Markdown reference pages	usage generate markdown	Markdown
Man pages	usage generate manpage	Manpages
Typed TypeScript and Python clients	usage generate sdk	SDK generation
Parse tables for a Go CLI	usage generate go	Go preview
A JSON Schema for the CLI's config file	usage generate json-schema	reference
A shell script with parsed arguments and --help	usage bash, usage exec	Scripts
What changed between two versions of an interface	usage diff	Comparing specs
What a command line binds to, and why	usage explain	reference
Mistakes a spec can have and still parse	usage lint	reference
A CLI described to an AI agent, with each command's effect	usage mcp	reference

Most of these read a spec the same way: -f takes a .usage.kdl file, a script whose #USAGE comments declare one, or - for stdin. --spec passes one as a string instead, and generate completion will run a command that prints one, so that a completion script follows whichever version of the CLI is installed. A binary built with the Rust framework prints its own spec, so documenting it needs no file at all:

mycli __usage_spec__ | usage generate markdown --file - --multi --out-dir docs

The reference lists every command and flag. It is generated from usage's own spec by the command it documents.

Installation

mise-en-place

mise use -g usage

Cargo

cargo install usage-cli --locked

cargo-binstall fetches a prebuilt binary instead of compiling one:

cargo binstall usage-cli

Homebrew

brew install usage

Arch Linux

The package is in Extra:

pacman -S usage