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

exec

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

fish

Execute a shell script with the specified shell

generate

Generate completions, documentation, and other artifacts from usage specs

generate completion

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

generate completion-init

Generate a shell init script that auto-completes any usage shebang script on $PATH

generate fig

Generate Fig completion spec for Amazon Q / Fig

generate json

Outputs a usage spec in json format

generate manpage

generate markdown

Generate markdown documentation from usage specs

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

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>

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

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

<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

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

-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