.TH USAGE-CLI 1
.SH NAME
usage\-cli \- CLI for working with usage\-based CLIs
.SH SYNOPSIS
\fBusage\fR [OPTIONS] [<COMPLETIONS>] [COMMAND]
.SH DESCRIPTION
CLI for working with usage\-based CLIs
.PP
.SH OPTIONS
.TP
\fB\-\-usage\-spec\fR
Outputs a `usage.kdl` spec for this CLI itself
.SH ARGUMENTS
.TP
\fB<COMPLETIONS>\fR
Outputs completions for the specified shell for completing the `usage` 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
\fBexec\fR
Execute a script, parsing args and exposing them as environment variables
.RS
\fIAliases: \fRx
.RE
.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 fig\fR
Generate Fig completion spec for Amazon Q / Fig
.TP
\fBgenerate json\fR
Outputs a usage spec in json format
.TP
\fBgenerate manpage\fR
.RS
\fIAliases: \fRman
.RE
.TP
\fBgenerate markdown\fR
Generate markdown documentation from usage specs
.RS
\fIAliases: \fRmd
.RE
.TP
\fBlint\fR
Lint a usage spec file for common issues
.TP
\fBpowershell\fR
Execute a shell script with the specified shell
.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
.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
.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 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 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
.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\-f, \-\-file\fR \fI<FILE>\fR
A .usage.kdl spec file to use for generating completions
.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\-\-include\-bash\-completion\-lib\fR
Include https://github.com/scop/bash\-completion
This is required for usage completions to work in bash, but the user may already provide it
.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
.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 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
.TP
\fB\-\-out\-file\fR \fI<OUT_FILE>\fR
File path where the generated Fig spec will be saved
.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
.TP
\fB\-\-spec\fR \fI<SPEC>\fR
raw string spec input
.SH "USAGE GENERATE MANPAGE"
\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
.TP
\fB\-o, \-\-out\-file\fR \fI<OUT_FILE>\fR
Output file path (defaults to stdout)
.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
.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
.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 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
\fBArguments:\fR
.PP
.TP
\fB<FILE>\fR
A usage spec file to lint
.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
.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