USAGE-CLI(1)

NAME
usage-cli - CLI for working with usage-based CLIs

SYNOPSIS
usage [OPTIONS] [<COMPLETIONS>] [COMMAND]

DESCRIPTION
CLI for working with usage-based CLIs

OPTIONS

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

ARGUMENTS

<COMPLETIONS>
    Outputs completions for the specified shell for completing the `usage` 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

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

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 json
    Outputs a usage spec in json format

generate manpage
    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

powershell
    Execute a shell script with the specified shell

sponsors
    Show the companies sponsoring usage and the en.dev project family

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

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

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

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

Options:

-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

--include-bash-completion-lib
    Include https://github.com/scop/bash-completion This is required for usage completions to work in bash, but the user may already provide it

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

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

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

USAGE GENERATE MANPAGE
Usage: usage generate manpage [OPTIONS]

Options:

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

-o, --out-file <OUT_FILE>
    Output file path (defaults to stdout)

-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

-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

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

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

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

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