.TH USAGE 1
.SH NAME
usage \- Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one
.SH SYNOPSIS
\fBusage\fR <COMMAND>
\fBusage\fR \-\-completions <COMPLETIONS>
\fBusage\fR \-\-usage\-spec
.SH DESCRIPTION
Generate completions, docs, manpages, and SDKs from a usage spec, and run scripts that carry one
.PP
A usage spec describes a CLI's commands, flags, and arguments once, in KDL. Most commands here read one: a `.usage.kdl` file given with `\-f`, a script whose `#USAGE` comments declare it, or `\-` for stdin. A binary built with the Rust framework prints its own spec, so a pipeline like `mycli __usage_spec__ | usage generate markdown \-f \-` needs no file at all.
.PP
Guides and a reference for every command: https://usage.jdx.dev/cli/
.PP
.SH OPTIONS
.TP
\fB\-\-completions\fR \fI<COMPLETIONS>\fR
Print a completion script for the `usage` CLI itself, for the named shell
.TP
\fB\-\-usage\-spec\fR
Print the usage spec for the `usage` CLI itself
.TP
\fB\-h, \-\-help\fR
Print help
.TP
\fB\-V, \-\-version\fR
Print version
.SH COMMANDS
.TP
\fBbash\fR
Run a script whose usage spec is written in its own comments
.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
Run a script through any interpreter, with its parsed arguments as environment variables
.RS
\fIAliases: \fRx
.RE
.TP
\fBexplain\fR
Explain what a command line binds to
.TP
\fBfish\fR
Run a script whose usage spec is written in its own comments
.TP
\fBgenerate\fR
Generate completions, docs, manpages, SDKs, and parse tables from a usage spec
.RS
\fIAliases: \fRg
.RE
.TP
\fBgenerate completion\fR
Generate a shell completion script for bash, fish, nu, powershell, or zsh
.RS
\fIAliases: \fRc
.RE
.TP
\fBgenerate completion\-init\fR
Generate a shell init script that completes every usage\-shebang script on PATH
.RS
\fIAliases: \fRci
.RE
.TP
\fBgenerate fig\fR
Generate a Fig completion spec, for Amazon Q and Fig
.TP
\fBgenerate go\fR
Generate Go parse tables from a usage spec
.TP
\fBgenerate json\fR
Print a usage spec as JSON
.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 a usage spec
.RS
\fIAliases: \fRmd
.RE
.TP
\fBgenerate sdk\fR
Generate a type\-safe SDK from a usage spec
.TP
\fBlint\fR
Lint a usage spec for mistakes that still parse
.TP
\fBmcp\fR
Serve a usage spec over the Model Context Protocol
.RS
\fIAliases: \fRmcp\-server
.RE
.TP
\fBpowershell\fR
Run a script whose usage spec is written in its own comments
.TP
\fBsponsors\fR
Show the companies sponsoring usage and the jdx.dev open source tools
.TP
\fBzsh\fR
Run a script whose usage spec is written in its own comments
.SH "USAGE BASH"
Run a script whose usage spec is written in its own comments
Usually reached through the script's shebang: the kernel hands the
script and its arguments to `usage`, which parses them against the
`#USAGE` lines at the top of the file, then runs the script with this
shell. Each flag and argument reaches the script as an environment
variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
one string, joined with `shell_words::join()` so that an element
containing a space stays quoted.
`\-h` and `\-\-help` print the script's help page rather than this one.
This command's shebang is `#!/usr/bin/env \-S usage bash`, and the
program it runs is `bash` from PATH. `USAGECLI_SHELL_BASH` names a
different one, which is how it is pointed at Git Bash on a Windows
machine where `bash` is the WSL launcher.
.PP
\fBUsage:\fR usage bash [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Print the script's help page instead of running it
.TP
\fB\-\-help\fR
Print the script's help page instead of running it
\fBArguments:\fR
.PP
.TP
\fB<SCRIPT>\fR
The script to run; its spec is read from the `#USAGE` comments at the top of the file
.TP
\fB<ARGS>\fR
Arguments to pass to the 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
What the scripts from `usage generate completion` run on every Tab: they pass the words typed so far and read back one candidate per line. Useful by hand, too, for checking what a spec offers at a given point without installing anything.
.PP
\fBUsage:\fR usage complete\-word [OPTIONS] [<WORDS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads stdin
.TP
\fB\-s, \-\-spec\fR \fI<SPEC>\fR
The spec itself, as a string, instead of a file
.TP
\fB\-\-cword\fR \fI<CWORD>\fR
Index of the word being completed; defaults to the last word
.TP
\fB\-\-shell\fR \fI<SHELL>\fR
The shell the candidates are for, which decides how they are quoted
.RS
\fIDefault: \fRbash
.RE
.TP
\fB\-h, \-\-help\fR
Print help
\fBArguments:\fR
.PP
.TP
\fB<WORDS>\fR
The words typed so far, starting with the program name
.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
.TP
\fB\-h, \-\-help\fR
Print help
\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"
Run a script through any interpreter, with its parsed arguments as environment variables
For scripts in a language `usage` has no dedicated command for. A shebang of `#!/usr/bin/env \-S usage exec node` parses the arguments against the `USAGE` comments at the top of the file, then runs `node <script> <args>` with each flag and argument exported as `usage_<name>`. When a file named `.<script>.usage.kdl` sits beside the script, the spec is read from it instead of from the comments.
`\-h` and `\-\-help` belong to the script once one is named, so they print its help page rather than this one. Asked with no script to describe, they print this page.
.PP
\fBUsage:\fR usage exec [OPTIONS] <COMMAND> <BIN> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Print the script's help page instead of running it
.TP
\fB\-\-help\fR
Print the script's help page instead of running it
\fBArguments:\fR
.PP
.TP
\fB<COMMAND>\fR
The interpreter to run the script with, such as `node` or `python3`
.TP
\fB<BIN>\fR
The script to run
.TP
\fB<ARGS>\fR
Arguments to pass to the 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 a script with a usage shebang; "\-" reads stdin
.TP
\fB\-s, \-\-spec\fR \fI<SPEC>\fR
The spec itself, as a string, instead of a file
.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.
.TP
\fB\-h, \-\-help\fR
Print help
\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"
Run a script whose usage spec is written in its own comments
Usually reached through the script's shebang: the kernel hands the
script and its arguments to `usage`, which parses them against the
`#USAGE` lines at the top of the file, then runs the script with this
shell. Each flag and argument reaches the script as an environment
variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
one string, joined with `shell_words::join()` so that an element
containing a space stays quoted.
`\-h` and `\-\-help` print the script's help page rather than this one.
This command's shebang is `#!/usr/bin/env \-S usage fish`, and the
program it runs is `fish` from PATH. `USAGECLI_SHELL_FISH` names a
different one.
.PP
\fBUsage:\fR usage fish [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Print the script's help page instead of running it
.TP
\fB\-\-help\fR
Print the script's help page instead of running it
\fBArguments:\fR
.PP
.TP
\fB<SCRIPT>\fR
The script to run; its spec is read from the `#USAGE` comments at the top of the file
.TP
\fB<ARGS>\fR
Arguments to pass to the 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"
Generate completions, docs, manpages, SDKs, and parse tables from a usage spec
.PP
\fBUsage:\fR usage generate [OPTIONS] <COMMAND>
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE GENERATE COMPLETION"
Generate a shell completion script for bash, fish, nu, powershell, or zsh
The script is a shim: on each Tab it hands the words typed so far to `usage complete\-word`, so `usage` must be installed wherever the script is. The spec comes from `\-\-file`, or from running `\-\-usage\-cmd` at completion time, which keeps a CLI that prints its own spec from ever going stale.
.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 spec file, or a script with a usage shebang; "\-" reads stdin
.TP
\fB\-\-cache\-key\fR \fI<CACHE_KEY>\fR
Cache what \-\-usage\-cmd prints under this key, so it runs once per key rather than on every Tab; the CLI's version is a good key
.TP
\fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
The `usage` executable the script calls back to, when it is not `usage` on PATH
.RS
\fIDefault: \fRusage
.RE
.RS
\fIEnvironment: \fR\fBJDX_USAGE_BIN\fR
.RE
.TP
\fB\-\-usage\-cmd\fR \fI<USAGE_CMD>\fR
A command that prints the CLI's spec, run in place of reading \-\-file
For a CLI that answers with its own spec, such as `mycli __usage_spec__`, so the script always completes the version that is installed. Required unless \-\-file is given.
.TP
\fB\-h, \-\-help\fR
Print help
\fBArguments:\fR
.PP
.TP
\fB<SHELL>\fR
The shell to generate the script for
.TP
\fB<BIN>\fR
The name of the CLI being completed, as it is typed at the prompt
.SH "USAGE GENERATE COMPLETION-INIT"
Generate a shell init script that completes every usage\-shebang script on PATH
Source it once from the shell's rc file and Tab works on any executable whose first line is a `usage` shebang, with no per\-script `usage generate completion` step. bash and zsh register a fallback completer that asks `usage complete\-word` when the command has such a shebang; fish has no fallback, so it scans PATH once at startup and registers each script it finds.
.PP
\fBUsage:\fR usage generate completion\-init [OPTIONS] <SHELL>
.PP
\fBOptions:\fR
.PP
.TP
\fB\-\-usage\-bin\fR \fI<USAGE_BIN>\fR
The `usage` executable the script calls back to, when it is not `usage` on PATH
.RS
\fIDefault: \fRusage
.RE
.RS
\fIEnvironment: \fR\fBJDX_USAGE_BIN\fR
.RE
.TP
\fB\-h, \-\-help\fR
Print help
\fBArguments:\fR
.PP
.TP
\fB<SHELL>\fR
The shell to generate the script for
.SH "USAGE GENERATE FIG"
Generate a Fig completion spec, for Amazon Q and Fig
.PP
\fBUsage:\fR usage generate fig [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads stdin
.TP
\fB\-\-out\-file\fR \fI<OUT_FILE>\fR
Where to write the spec, or "\-" for stdout (default)
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
The spec itself, as a string, instead of a file
.TP
\fB\-h, \-\-help\fR
Print help
.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 file, or a script with a usage shebang; "\-" reads stdin
.TP
\fB\-o, \-\-out\-file\fR \fI<OUT_FILE>\fR
Where to write the Go source, or "\-" for stdout (default)
.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
The spec itself, as a string, instead of a file
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE GENERATE JSON"
Print a usage spec as JSON
The same document the KDL describes, with included files merged and defaults filled in, for a tool that would rather not parse KDL itself.
.PP
\fBUsage:\fR usage generate json [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads stdin
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
The spec itself, as a string, instead of a file
.TP
\fB\-\-view\fR \fI<VIEW>\fR
Render one spec\-declared executable view
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE GENERATE JSON-SCHEMA"
Generate a JSON Schema for a CLI's config file from its usage spec
Built from the spec's `config` block: each `prop` becomes a property with its type, default, and help, so an editor can complete and validate the file the CLI reads. A spec whose settings cannot live in a file is an error rather than an empty schema.
.PP
\fBUsage:\fR usage generate json\-schema [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads 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
The spec itself, as a string, instead of a file
.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`
.TP
\fB\-h, \-\-help\fR
Print help
.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 file, or a script with a usage shebang; "\-" reads 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
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE GENERATE MARKDOWN"
Generate Markdown documentation from a usage spec
One page by default, or a page per command with \-\-multi. Every part of the output comes from a Tera template that \-\-template can replace.
.PP
\fBUsage:\fR usage generate markdown [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads 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
Directory for the per\-command pages (required with \-\-multi)
.TP
\fB\-\-out\-file\fR \fI<OUT_FILE>\fR
Output file path for single\-file markdown generation, or "\-" for stdout (default)
.TP
\fB\-\-indented\-blocks\-to\-code\-fences\fR
Turn four\-space indented blocks in help text into markdown code fences
`\-\-replace\-pre\-with\-code\-fences` is the former name and still works. It was always a misnomer: this has never looked at `<pre>` tags.
.TP
\fB\-\-url\-prefix\fR \fI<URL_PREFIX>\fR
Prefix for the links between pages, such as /cli/reference
.TP
\fB\-\-link\-extension\fR \fI<LINK_EXTENSION>\fR
Extension for page links (including the dot); empty means extensionless URLs
.RS
\fIDefault: \fR.md
.RE
.TP
\fB\-\-template\fR \fI<TEMPLATE>\fR
Replace a built\-in Tera template, as NAME=PATH; the names are spec, index, command, argument, flag, and config
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE GENERATE SDK"
Generate a type\-safe SDK from a usage spec
The SDK is a subprocess wrapper: typed arguments, flags, and choices for every command, and a client that builds the argument list and runs the binary.
.PP
\fBUsage:\fR usage generate sdk [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads stdin
.TP
\fB\-l, \-\-language\fR \fI<LANGUAGE>\fR
Target language for the SDK
.TP
\fB\-o, \-\-output\fR \fI<OUTPUT>\fR
Directory to write the SDK into
.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
The spec itself, as a string, instead of a file
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE LINT"
Lint a usage spec for mistakes that still parse
A spec can be valid KDL and still be wrong: a flag or subcommand declared twice, a required argument after an optional one, a variadic argument that is not last, a command or flag with no help, an example its own spec cannot parse. Each finding carries a code such as `duplicate\-flag`, and `\-\-format json` prints the findings as a list for a script to act on.
Exits 1 when there is an error, or a warning under `\-\-warnings\-as\-errors`.
.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.
.TP
\fB\-h, \-\-help\fR
Print help
\fBArguments:\fR
.PP
.TP
\fB<FILE>\fR
A usage spec file, or a script with a usage shebang; "\-" reads 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`.
Two tools are served: `list_commands`, every command with its effect, and
`describe_command`, one command's help, flags, and arguments. Together they
let an agent learn what a CLI does, and what running it would touch, without
running it.
.PP
\fBUsage:\fR usage mcp [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-f, \-\-file\fR \fI<FILE>\fR
A usage spec file, or a script with a usage shebang (not "\-": stdin is the MCP transport)
.TP
\fB\-s, \-\-spec\fR \fI<SPEC>\fR
The spec itself, as a string, instead of a file
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE POWERSHELL"
Run a script whose usage spec is written in its own comments
Usually reached through the script's shebang: the kernel hands the
script and its arguments to `usage`, which parses them against the
`#USAGE` lines at the top of the file, then runs the script with this
shell. Each flag and argument reaches the script as an environment
variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
one string, joined with `shell_words::join()` so that an element
containing a space stays quoted.
`\-h` and `\-\-help` print the script's help page rather than this one.
This command's shebang is `#!/usr/bin/env \-S usage powershell`, and
the program it runs is `pwsh` from PATH. `USAGECLI_SHELL_PWSH` names a
different one, which is also how it is pointed at `powershell.exe` on a
machine that has only Windows PowerShell.
.PP
\fBUsage:\fR usage powershell [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Print the script's help page instead of running it
.TP
\fB\-\-help\fR
Print the script's help page instead of running it
\fBArguments:\fR
.PP
.TP
\fB<SCRIPT>\fR
The script to run; its spec is read from the `#USAGE` comments at the top of the file
.TP
\fB<ARGS>\fR
Arguments to pass to the 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 SPONSORS"
Show the companies sponsoring usage and the jdx.dev open source tools
.PP
\fBUsage:\fR usage sponsors [OPTIONS]
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h, \-\-help\fR
Print help
.SH "USAGE ZSH"
Run a script whose usage spec is written in its own comments
Usually reached through the script's shebang: the kernel hands the
script and its arguments to `usage`, which parses them against the
`#USAGE` lines at the top of the file, then runs the script with this
shell. Each flag and argument reaches the script as an environment
variable named `usage_<name>`, so `\-\-force` becomes `usage_force` and
`<file>` becomes `usage_file`. A value declared `var=#true` arrives as
one string, joined with `shell_words::join()` so that an element
containing a space stays quoted.
`\-h` and `\-\-help` print the script's help page rather than this one.
This command's shebang is `#!/usr/bin/env \-S usage zsh`, and the
program it runs is `zsh` from PATH. `USAGECLI_SHELL_ZSH` names a
different one.
.PP
\fBUsage:\fR usage zsh [OPTIONS] <SCRIPT> [<ARGS>] ...
.PP
\fBOptions:\fR
.PP
.TP
\fB\-h\fR
Print the script's help page instead of running it
.TP
\fB\-\-help\fR
Print the script's help page instead of running it
\fBArguments:\fR
.PP
.TP
\fB<SCRIPT>\fR
The script to run; its spec is read from the `#USAGE` comments at the top of the file
.TP
\fB<ARGS>\fR
Arguments to pass to the 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