usage-cli 6.1.0

.TH USAGE 1
.SH NAME
usage \- CLI for working with usage\-based CLIs
.SH SYNOPSIS
\fBusage\fR <COMMAND>
\fBusage\fR \-\-completions <COMPLETIONS>
\fBusage\fR \-\-usage\-spec
.SH DESCRIPTION
CLI for working with usage\-based CLIs
.PP
.SH OPTIONS
.TP
\fB\-\-completions\fR \fI<COMPLETIONS>\fR
Outputs completions for the specified shell for completing the `usage` CLI itself
.TP
\fB\-\-usage\-spec\fR
Outputs a `usage.kdl` spec for this CLI itself
.SH COMMANDS
.TP
\fBbash\fR
Execute a shell script with the specified shell
.TP
\fBcomplete\-word\fR
Generate shell completion candidates for a partial command line
.RS
\fIAliases: \fRcw
.RE
.TP
\fBdiff\fR
Compare two usage specs and report what changed about the interface
.TP
\fBexec\fR
Execute a script, parsing args and exposing them as environment variables
.RS
\fIAliases: \fRx
.RE
.TP
\fBexplain\fR
Explain what a command line binds to
.TP
\fBfish\fR
Execute a shell script with the specified shell
.TP
\fBgenerate\fR
Generate completions, documentation, and other artifacts from usage specs
.RS
\fIAliases: \fRg
.RE
.TP
\fBgenerate completion\fR
Generate shell completion scripts for bash, fish, nu, powershell, or zsh
.RS
\fIAliases: \fRc
.RE
.TP
\fBgenerate completion\-init\fR
Generate a shell init script that auto\-completes any usage shebang script on $PATH
.RS
\fIAliases: \fRci
.RE
.TP
\fBgenerate fig\fR
Generate Fig completion spec for Amazon Q / Fig
.TP
\fBgenerate go\fR
Generate Go parse tables from a usage spec
.TP
\fBgenerate json\fR
Outputs a usage spec in json format
.TP
\fBgenerate json\-schema\fR
Generate a JSON Schema for a CLI's config file from its usage spec
.TP
\fBgenerate manpage\fR
Generate a manpage from a usage spec
.RS
\fIAliases: \fRman
.RE
.TP
\fBgenerate markdown\fR
Generate markdown documentation from usage specs
.RS
\fIAliases: \fRmd
.RE
.TP
\fBgenerate sdk\fR
Generate a type\-safe SDK from a usage spec
.TP
\fBlint\fR
Lint a usage spec file for common issues
.TP
\fBmcp\fR
Serve a usage spec over the Model Context Protocol
.RS
\fIAliases: \fRmcp\-server
.RE
.TP
\fBpowershell\fR
Execute a shell script with the specified shell
.TP
\fBsponsors\fR
Show the companies sponsoring usage and the jdx.dev open source tools
.TP
\fBzsh\fR
Execute a shell script with the specified shell
.SH "USAGE BASH"
Execute a shell script with the specified shell

Typically, this will be called by a script's shebang.

If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
to properly escape and quote values with spaces in them.
.PP
\fBUsage:\fR usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Show help
.TP
\fB\-\-help\fR
Show help
\fBArguments:\fR
.PP
.TP
\fB<ARGS>\fR
Arguments to pass to script

Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
.SH "USAGE COMPLETE-WORD"
Generate shell completion candidates for a partial command line

This is used internally by shell completion scripts to provide intelligent completions for commands, flags, and arguments.
.PP
\fBUsage:\fR usage complete\-word [OPTIONS] [<WORDS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
Usage spec file or script with usage shebang, use "\-" to read from stdin
.TP
\fB\-s, \-\-spec\fR \fI<SPEC>\fR
Raw string spec input
.TP
\fB\-\-cword\fR \fI<CWORD>\fR
Current word index
.TP
\fB\-\-shell\fR \fI<SHELL>\fR
.RS
\fIDefault: \fRbash
.RE
\fBArguments:\fR
.PP
.TP
\fB<WORDS>\fR
User's input from the command line
.SH "USAGE DIFF"
Compare two usage specs and report what changed about the interface

Findings are grouped into breaking changes (a command line that used to work
now fails, binds differently, or resolves to a different value), compatible
changes (the interface gained something or relaxed a rule), and metadata
changes (help text, effect, deprecation — nothing about parsing).

Exits 1 when there is a breaking change, so a release job can gate on it, and
either spec may be "\-":

  mycli \-\-usage\-spec | usage diff released.usage.kdl \-

`version` is ignored on purpose: a release bumps it, and a check that fires
every release does not get left switched on.
.PP
\fBUsage:\fR usage diff [OPTIONS] <OLD> <NEW>
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-format\fR \fI<FORMAT>\fR
Output format
.RS
\fIDefault: \fRtext
.RE
.TP
\fB\-b, \-\-breaking\fR
Report only breaking changes
.TP
\fB\-\-exit\-zero\fR
Exit 0 even when there are breaking changes
\fBArguments:\fR
.PP
.TP
\fB<OLD>\fR
The spec as it was, typically the released one, use "\-" to read from stdin
.TP
\fB<NEW>\fR
The spec as it is now, use "\-" to read from stdin
.SH "USAGE EXEC"
Execute a script, parsing args and exposing them as environment variables
.PP
\fBUsage:\fR usage exec [OPTIONS] <COMMAND> <BIN> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Show help
.TP
\fB\-\-help\fR
Show help
\fBArguments:\fR
.PP
.TP
\fB<COMMAND>\fR
command to execute after parsing usage spec
.TP
\fB<BIN>\fR
path to script to execute
.TP
\fB<ARGS>\fR
arguments to pass to script
.SH "USAGE EXPLAIN"
Explain what a command line binds to

Prints a row per argv token saying what it became, then the values that came from
somewhere other than argv, then anything that went wrong. Exits 0 even when the explained
command line does not parse: the report succeeded, and that is the case worth a report.
.PP
\fBUsage:\fR usage explain [OPTIONS] [<ARGV>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file or script with a usage shebang, use "\-" to read from stdin
.TP
\fB\-s, \-\-spec\fR \fI<SPEC>\fR
Raw string spec input
.TP
\fB\-\-format\fR \fI<FORMAT>\fR
Output format
.RS
\fIDefault: \fRtext
.RE
.TP
\fB\-\-view\fR \fI<VIEW>\fR
A spec\-declared executable view to explain
.TP
\fB\-e, \-\-env\fR \fI<ENV>\fR
Environment to explain against, as KEY=VALUE, repeatable

Given at all, these are the *whole* environment: an explanation pasted into a bug report has to mean the same thing on the machine that reads it. Omitted, the process environment is used, which is what an execution would see.
\fBArguments:\fR
.PP
.TP
\fB<ARGV>\fR
The command line to explain, starting with the program name

`usage`'s own flags come before it, and flag parsing ends at the program name, so both `explain \-f f.kdl mycli \-\-env=prod` and `explain \-f f.kdl \-\- mycli \-\-env=prod` work. Separate with `\-\-` when the explained line carries its own: the first `\-\-` is still `usage`'s separator, so `explain \-f f.kdl mycli a \-\- b` loses one.
.SH "USAGE FISH"
Execute a shell script with the specified shell

Typically, this will be called by a script's shebang.

If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
to properly escape and quote values with spaces in them.
.PP
\fBUsage:\fR usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Show help
.TP
\fB\-\-help\fR
Show help
\fBArguments:\fR
.PP
.TP
\fB<ARGS>\fR
Arguments to pass to script

Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
.SH "USAGE GENERATE COMPLETION"
Generate shell completion scripts for bash, fish, nu, powershell, or zsh
.PP
\fBUsage:\fR usage generate completion [OPTIONS] <SHELL> <BIN>
.PP
\fBOptions:\fR
.PP
.TP
\fB\-\-install\fR
Install the script where this shell looks for it, instead of printing it

Writes the script file and nothing else: no shell rc file and no PowerShell profile is edited. Where a shell needs a one\-time line of its own — zsh's `fpath+=`, PowerShell's dot\-source — it is printed for you to add.
.TP
\fB\-\-force\fR
Replace a file at the target path that usage did not write
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A .usage.kdl spec file to use for generating completions, use "\-" to read from stdin
.TP
\fB\-\-cache\-key\fR \fI<CACHE_KEY>\fR
A cache key to use for storing the results of calling the CLI with \-\-usage\-cmd
.TP
\fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
Override the bin used for calling back to usage\-cli

You may need to set this if you have a different bin named "usage"
.RS
\fIDefault: \fRusage
.RE
.RS
\fIEnvironment: \fR\fBJDX_USAGE_BIN\fR
.RE
.TP
\fB\-\-usage\-cmd\fR \fI<USAGE_CMD>\fR
A command which generates a usage spec e.g.: `mycli \-\-usage` or `mycli completion usage` Defaults to "$bin \-\-usage"
\fBArguments:\fR
.PP
.TP
\fB<SHELL>\fR
Shell to generate completions for
.TP
\fB<BIN>\fR
The CLI which we're generating completions for
.SH "USAGE GENERATE COMPLETION-INIT"
Generate a shell init script that auto\-completes any usage shebang script on $PATH

Source the output once from your shell rc (e.g. ~/.bashrc) to enable tab\-completion for any executable whose first line is a `usage` shebang — no per\-script `usage g completion` step required.
.PP
\fBUsage:\fR usage generate completion\-init [OPTIONS] <SHELL>
.PP
\fBOptions:\fR
.PP
.TP
\fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
Override the bin used for calling back to usage\-cli

You may need to set this if you have a different bin named "usage"
.RS
\fIDefault: \fRusage
.RE
.RS
\fIEnvironment: \fR\fBJDX_USAGE_BIN\fR
.RE
\fBArguments:\fR
.PP
.TP
\fB<SHELL>\fR
Shell to generate the init script for
.SH "USAGE GENERATE FIG"
Generate Fig completion spec for Amazon Q / Fig
.PP
\fBUsage:\fR usage generate fig [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file, use "\-" to read from stdin
.TP
\fB\-\-out\-file\fR \fI<OUT_FILE>\fR
File path where the generated Fig spec will be saved, or "\-" for stdout
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
Raw string spec input
.SH "USAGE GENERATE GO"
Generate Go parse tables from a usage spec

The tables are read by github.com/jdx/usage/go/argv. Go has no macros, so what a Rust CLI gets from a derive at compile time, a Go CLI gets from this at build time — typically from a `go:generate` line:

  //go:generate usage generate go \-f mycli.usage.kdl \-o tables.go
.PP
\fBUsage:\fR usage generate go [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file, use "\-" to read from stdin
.TP
\fB\-o, \-\-out\-file\fR \fI<OUT_FILE>\fR
File path where the generated Go source will be saved, or "\-" for stdout
.TP
\fB\-p, \-\-package\fR \fI<PACKAGE>\fR
Go package clause for the generated file (defaults to the spec's bin name)
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
Raw string spec input
.SH "USAGE GENERATE JSON"
Outputs a usage spec in json format
.PP
\fBUsage:\fR usage generate json [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file, use "\-" to read from stdin
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
raw string spec input
.TP
\fB\-\-view\fR \fI<VIEW>\fR
Render one spec\-declared executable view
.SH "USAGE GENERATE JSON-SCHEMA"
Generate a JSON Schema for a CLI's config file from its usage spec
.PP
\fBUsage:\fR usage generate json\-schema [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file, use "\-" to read from stdin
.TP
\fB\-\-out\-file\fR \fI<OUT_FILE>\fR
Write the schema here instead of to stdout
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
raw string spec input
.TP
\fB\-\-title\fR \fI<TITLE>\fR
The schema's title, shown by editors
.TP
\fB\-\-url\fR \fI<URL>\fR
Where the schema is published, for its `$id`
.SH "USAGE GENERATE MANPAGE"
Generate a manpage from a usage spec
.PP
\fBUsage:\fR usage generate manpage [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file, use "\-" to read from stdin
.TP
\fB\-\-view\fR \fI<VIEW>\fR
Render one spec\-declared executable view
.TP
\fB\-o, \-\-out\-file\fR \fI<OUT_FILE>\fR
Output file path, or "\-" for stdout (default)
.TP
\fB\-s, \-\-section\fR \fI<SECTION>\fR
Manual section number (default: 1)

Common sections: \- 1: User commands \- 5: File formats \- 7: Miscellaneous \- 8: System administration commands
.RS
\fIDefault: \fR1
.RE
.SH "USAGE GENERATE MARKDOWN"
Generate markdown documentation from usage specs
.PP
\fBUsage:\fR usage generate markdown [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file, use "\-" to read from stdin
.TP
\fB\-\-view\fR \fI<VIEW>\fR
Render one spec\-declared executable view
.TP
\fB\-m, \-\-multi\fR
Render each subcommand as a separate markdown file
.TP
\fB\-\-html\-encode\fR
Escape HTML in markdown
.TP
\fB\-\-out\-dir\fR \fI<OUT_DIR>\fR
Output markdown files to this directory (required when using \-\-multi)
.TP
\fB\-\-out\-file\fR \fI<OUT_FILE>\fR
Output file path for single\-file markdown generation, or "\-" for stdout (default)
.TP
\fB\-\-replace\-pre\-with\-code\-fences\fR
Replace `<pre>` tags with markdown code fences
.TP
\fB\-\-url\-prefix\fR \fI<URL_PREFIX>\fR
Prefix to add to all URLs
.SH "USAGE GENERATE SDK"
Generate a type\-safe SDK from a usage spec
.PP
\fBUsage:\fR usage generate sdk [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec taken in as a file
.TP
\fB\-l, \-\-language\fR \fI<LANGUAGE>\fR
Target language for the SDK
.TP
\fB\-o, \-\-output\fR \fI<OUTPUT>\fR
Output directory for generated SDK files
.TP
\fB\-p, \-\-package\-name\fR \fI<PACKAGE_NAME>\fR
Override the package/module name (defaults to spec bin name)
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
Raw string spec input
.SH "USAGE LINT"
Lint a usage spec file for common issues
.PP
\fBUsage:\fR usage lint [OPTIONS] <FILE>
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-format\fR \fI<FORMAT>\fR
Output format
.RS
\fIDefault: \fRtext
.RE
.TP
\fB\-W, \-\-warnings\-as\-errors\fR
Treat warnings as errors
.TP
\fB\-\-sorted\fR
Also check that subcommands and flags are declared in sorted order

Off by default: declaration order is a house convention rather than a correctness question, so a spec that keeps a different order is not wrong. Pair it with \-\-warnings\-as\-errors to hold the order in CI.
\fBArguments:\fR
.PP
.TP
\fB<FILE>\fR
A usage spec file to lint, use "\-" to read from stdin
.SH "USAGE MCP"
Serve a usage spec over the Model Context Protocol

Reads JSON\-RPC over stdin and writes responses to stdout, which is how MCP
clients launch a local server. Point one at `usage mcp \-f mycli.usage.kdl`.
.PP
\fBUsage:\fR usage mcp [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
Usage spec file (not "\-": stdin is the MCP transport)
.TP
\fB\-s, \-\-spec\fR \fI<SPEC>\fR
Raw string spec input
.SH "USAGE POWERSHELL"
Execute a shell script with the specified shell

Typically, this will be called by a script's shebang.

If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
to properly escape and quote values with spaces in them.
.PP
\fBUsage:\fR usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Show help
.TP
\fB\-\-help\fR
Show help
\fBArguments:\fR
.PP
.TP
\fB<ARGS>\fR
Arguments to pass to script

Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
.SH "USAGE ZSH"
Execute a shell script with the specified shell

Typically, this will be called by a script's shebang.

If using `var=#true` on args/flags, they will be joined with spaces using `shell_words::join()`
to properly escape and quote values with spaces in them.
.PP
\fBUsage:\fR usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Show help
.TP
\fB\-\-help\fR
Show help
\fBArguments:\fR
.PP
.TP
\fB<ARGS>\fR
Arguments to pass to script

Anything `usage` does not recognise is a value rather than a mistake, which is what lets a shebang script take flags of its own.
.SH SOURCE
https://github.com/jdx/usage