USAGE(1)

NAME
usage - CLI for working with usage-based CLIs

SYNOPSIS
usage <COMMAND> usage --completions <COMPLETIONS> usage --usage-spec

DESCRIPTION
CLI for working with usage-based CLIs

OPTIONS

--completions <COMPLETIONS>
    Outputs completions for the specified shell for completing the `usage` CLI itself

--usage-spec
    Outputs a `usage.kdl` spec for this CLI itself

COMMANDS

bash
    Execute a shell script with the specified shell

complete-word
    Generate shell completion candidates for a partial command line
    Aliases: cw

diff
    Compare two usage specs and report what changed about the interface

exec
    Execute a script, parsing args and exposing them as environment variables
    Aliases: x

explain
    Explain what a command line binds to

fish
    Execute a shell script with the specified shell

generate
    Generate completions, documentation, and other artifacts from usage specs
    Aliases: g

generate completion
    Generate shell completion scripts for bash, fish, nu, powershell, or zsh
    Aliases: c

generate completion-init
    Generate a shell init script that auto-completes any usage shebang script on $PATH
    Aliases: ci

generate fig
    Generate Fig completion spec for Amazon Q / Fig

generate go
    Generate Go parse tables from a usage spec

generate json
    Outputs a usage spec in json format

generate json-schema
    Generate a JSON Schema for a CLI's config file from its usage spec

generate manpage
    Generate a manpage from a usage spec
    Aliases: man

generate markdown
    Generate markdown documentation from usage specs
    Aliases: md

generate sdk
    Generate a type-safe SDK from a usage spec

lint
    Lint a usage spec file for common issues

mcp Serve a usage spec over the Model Context Protocol
    Aliases: mcp-server

powershell
    Execute a shell script with the specified shell

sponsors
    Show the companies sponsoring usage and the jdx.dev open source tools

zsh Execute a shell script with the specified shell

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.

Usage: usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...

Options:

-h  Show help

--help
    Show help Arguments:

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

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.

Usage: usage complete-word [OPTIONS] [<WORDS>] ...

Options:

-f, --file <FILE>
    Usage spec file or script with usage shebang, use "-" to read from stdin

-s, --spec <SPEC>
    Raw string spec input

--cword <CWORD>
    Current word index

--shell <SHELL>
    Default: bash
Arguments:

<WORDS>
    User's input from the command line

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.

Usage: usage diff [OPTIONS] <OLD> <NEW>

Options:

-f, --format <FORMAT>
    Output format
    Default: text

-b, --breaking
    Report only breaking changes

--exit-zero
    Exit 0 even when there are breaking changes Arguments:

<OLD>
    The spec as it was, typically the released one, use "-" to read from stdin

<NEW>
    The spec as it is now, use "-" to read from stdin

USAGE EXEC
Execute a script, parsing args and exposing them as environment variables

Usage: usage exec [OPTIONS] <COMMAND> <BIN> [<ARGS>] ...

Options:

-h  Show help

--help
    Show help Arguments:

<COMMAND>
    command to execute after parsing usage spec

<BIN>
    path to script to execute

<ARGS>
    arguments to pass to script

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.

Usage: usage explain [OPTIONS] [<ARGV>] ...

Options:

-f, --file <FILE>
    A usage spec file or script with a usage shebang, use "-" to read from stdin

-s, --spec <SPEC>
    Raw string spec input

--format <FORMAT>
    Output format
    Default: text

--view <VIEW>
    A spec-declared executable view to explain

-e, --env <ENV>
    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. Arguments:

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

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.

Usage: usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...

Options:

-h  Show help

--help
    Show help Arguments:

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

USAGE GENERATE COMPLETION
Generate shell completion scripts for bash, fish, nu, powershell, or zsh

Usage: usage generate completion [OPTIONS] <SHELL> <BIN>

Options:

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

--force
    Replace a file at the target path that usage did not write

-f, --file <FILE>
    A .usage.kdl spec file to use for generating completions, use "-" to read from stdin

--cache-key <CACHE_KEY>
    A cache key to use for storing the results of calling the CLI with --usage-cmd

--usage-bin <USAGE_BIN>
    Override the bin used for calling back to usage-cli You may need to set this if you have a different bin named "usage"
    Default: usage
    Environment: JDX_USAGE_BIN

--usage-cmd <USAGE_CMD>
    A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage" Arguments:

<SHELL>
    Shell to generate completions for

<BIN>
    The CLI which we're generating completions for

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.

Usage: usage generate completion-init [OPTIONS] <SHELL>

Options:

--usage-bin <USAGE_BIN>
    Override the bin used for calling back to usage-cli You may need to set this if you have a different bin named "usage"
    Default: usage
    Environment: JDX_USAGE_BIN
Arguments:

<SHELL>
    Shell to generate the init script for

USAGE GENERATE FIG
Generate Fig completion spec for Amazon Q / Fig

Usage: usage generate fig [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file, use "-" to read from stdin

--out-file <OUT_FILE>
    File path where the generated Fig spec will be saved, or "-" for stdout

--spec <SPEC>
    Raw string spec input

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

Usage: usage generate go [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file, use "-" to read from stdin

-o, --out-file <OUT_FILE>
    File path where the generated Go source will be saved, or "-" for stdout

-p, --package <PACKAGE>
    Go package clause for the generated file (defaults to the spec's bin name)

--spec <SPEC>
    Raw string spec input

USAGE GENERATE JSON
Outputs a usage spec in json format

Usage: usage generate json [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file, use "-" to read from stdin

--spec <SPEC>
    raw string spec input

--view <VIEW>
    Render one spec-declared executable view

USAGE GENERATE JSON-SCHEMA
Generate a JSON Schema for a CLI's config file from its usage spec

Usage: usage generate json-schema [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file, use "-" to read from stdin

--out-file <OUT_FILE>
    Write the schema here instead of to stdout

--spec <SPEC>
    raw string spec input

--title <TITLE>
    The schema's title, shown by editors

--url <URL>
    Where the schema is published, for its `$id`

USAGE GENERATE MANPAGE
Generate a manpage from a usage spec

Usage: usage generate manpage [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file, use "-" to read from stdin

--view <VIEW>
    Render one spec-declared executable view

-o, --out-file <OUT_FILE>
    Output file path, or "-" for stdout (default)

-s, --section <SECTION>
    Manual section number (default: 1) Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands
    Default: 1

USAGE GENERATE MARKDOWN
Generate markdown documentation from usage specs

Usage: usage generate markdown [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file, use "-" to read from stdin

--view <VIEW>
    Render one spec-declared executable view

-m, --multi
    Render each subcommand as a separate markdown file

--html-encode
    Escape HTML in markdown

--out-dir <OUT_DIR>
    Output markdown files to this directory (required when using --multi)

--out-file <OUT_FILE>
    Output file path for single-file markdown generation, or "-" for stdout (default)

--replace-pre-with-code-fences
    Replace `<pre>` tags with markdown code fences

--url-prefix <URL_PREFIX>
    Prefix to add to all URLs

USAGE GENERATE SDK
Generate a type-safe SDK from a usage spec

Usage: usage generate sdk [OPTIONS]

Options:

-f, --file <FILE>
    A usage spec taken in as a file

-l, --language <LANGUAGE>
    Target language for the SDK

-o, --output <OUTPUT>
    Output directory for generated SDK files

-p, --package-name <PACKAGE_NAME>
    Override the package/module name (defaults to spec bin name)

--spec <SPEC>
    Raw string spec input

USAGE LINT
Lint a usage spec file for common issues

Usage: usage lint [OPTIONS] <FILE>

Options:

-f, --format <FORMAT>
    Output format
    Default: text

-W, --warnings-as-errors
    Treat warnings as errors

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

<FILE>
    A usage spec file to lint, use "-" to read from stdin

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

Usage: usage mcp [OPTIONS]

Options:

-f, --file <FILE>
    Usage spec file (not "-": stdin is the MCP transport)

-s, --spec <SPEC>
    Raw string spec input

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.

Usage: usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...

Options:

-h  Show help

--help
    Show help Arguments:

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

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.

Usage: usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...

Options:

-h  Show help

--help
    Show help Arguments:

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

SOURCE
https://github.com/jdx/usage