// @generated by usage-cli from its own parse tables
min_usage_version "4.0"
name usage
bin usage
version "6.1.1"
repository "https://github.com/jdx/usage"
source_code_link_template #"""
{%- set path = path | replace(from='-', to='_') -%}
{%- if cmd.subcommands | length > 0 -%}
{%- set path = path ~ "/mod.rs" -%}
{%- elif path in ["bash", "fish", "powershell", "zsh"] -%}
{%- set path = "shell.rs" -%}
{%- else -%}
{%- set path = path ~ ".rs" -%}
{%- endif -%}
https://github.com/jdx/usage/blob/main/cli/src/cli/{{path}}
"""#
about "CLI for working with usage-based CLIs"
usage #"""
Usage: usage <COMMAND>
       usage --completions <COMPLETIONS>
       usage --usage-spec
"""#
unknown_flags error
subcommand_required #true
flagset shell {
    flag -h help="Show help"
    flag --help help="Show help"
}
flag --completions help="Outputs completions for the specified shell for completing the `usage` CLI itself" {
    arg <COMPLETIONS>
}
flag --usage-spec help="Outputs a `usage.kdl` spec for this CLI itself"
cmd bash help="Execute a shell script using bash" unknown_flags=value {
    long_help #"""
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.
"""#
    use shell
    arg <SCRIPT>
    arg "[ARGS]..." help="Arguments to pass to script" {
        long_help #"""
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.
"""#
    }
}
cmd complete-word help="Generate shell completion candidates for a partial command line" effect=read {
    alias cw
    long_help #"""
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.
"""#
    flag "-f --file" help="Usage spec file or script with usage shebang, use \"-\" to read from stdin" {
        arg <FILE>
    }
    flag "-s --spec" help="Raw string spec input" overrides=--file required_unless=--file {
        arg <SPEC>
    }
    flag --cword help="Current word index" {
        arg <CWORD>
    }
    flag --shell default=bash {
        arg <SHELL> {
            choices bash fish nu powershell zsh
        }
    }
    arg "[WORDS]..." help="User's input from the command line"
}
cmd diff help="Compare two usage specs and report what changed about the interface" effect=read {
    long_help #"""
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.
"""#
    flag "-f --format" help="Output format" default=text {
        arg <FORMAT> {
            choices {
                choice text
                choice json
            }
        }
    }
    flag "-b --breaking" help="Report only breaking changes"
    flag --exit-zero help="Exit 0 even when there are breaking changes"
    arg <OLD> help="The spec as it was, typically the released one, use \"-\" to read from stdin"
    arg <NEW> help="The spec as it is now, use \"-\" to read from stdin"
    complete old type=path
    complete new type=path
}
cmd exec help="Execute a script, parsing args and exposing them as environment variables" unknown_flags=value {
    alias x
    flag -h help="Show help"
    flag --help help="Show help"
    arg <COMMAND> help="command to execute after parsing usage spec"
    arg <BIN> help="path to script to execute"
    arg "[ARGS]..." help="arguments to pass to script"
}
cmd explain help="Explain what a command line binds to" effect=read {
    long_help #"""
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.
"""#
    flag "-f --file" help="A usage spec file or script with a usage shebang, use \"-\" to read from stdin" {
        arg <FILE>
    }
    flag "-s --spec" help="Raw string spec input" overrides=--file required_unless=--file {
        arg <SPEC>
    }
    flag --format help="Output format" default=text {
        arg <FORMAT> {
            choices {
                choice text
                choice json
            }
        }
    }
    flag --view help="A spec-declared executable view to explain" {
        arg <VIEW>
    }
    flag "-e --env" help="Environment to explain against, as KEY=VALUE, repeatable" var=#true {
        long_help #"""
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.
"""#
        arg <ENV>
    }
    arg "[ARGV]..." help="The command line to explain, starting with the program name" double_dash=automatic {
        long_help #"""
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.
"""#
    }
    complete argv type=command_args
    complete file type=path
}
cmd fish help="Execute a shell script using fish" unknown_flags=value {
    long_help #"""
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.
"""#
    use shell
    arg <SCRIPT>
    arg "[ARGS]..." help="Arguments to pass to script" {
        long_help #"""
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.
"""#
    }
}
cmd generate help="Generate completions, documentation, and other artifacts from usage specs" effect=read subcommand_required=#true {
    alias g
    cmd completion help="Generate shell completion scripts for bash, fish, nu, powershell, or zsh" effect=read {
        alias c
        alias complete hide=#true
        alias completions hide=#true
        flag --install help="Install the script where this shell looks for it, instead of printing it" effect=write {
            long_help #"""
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.
"""#
        }
        flag --force help="Replace a file at the target path that usage did not write" effect=write requires=--install
        flag "-f --file" help="A .usage.kdl spec file to use for generating completions, use \"-\" to read from stdin" {
            arg <FILE>
        }
        flag --cache-key help="A cache key to use for storing the results of calling the CLI with --usage-cmd" requires=--usage-cmd {
            arg <CACHE_KEY>
        }
        flag --usage-bin help="Override the bin used for calling back to usage-cli" env=JDX_USAGE_BIN default=usage {
            long_help #"""
Override the bin used for calling back to usage-cli

You may need to set this if you have a different bin named "usage"
"""#
            arg <USAGE_BIN>
        }
        flag --usage-cmd help="A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to \"$bin --usage\"" required_unless=--file {
            arg <USAGE_CMD>
        }
        arg <SHELL> help="Shell to generate completions for" {
            choices bash fish nu powershell zsh
        }
        arg <BIN> help="The CLI which we're generating completions for"
    }
    cmd completion-init help="Generate a shell init script that auto-completes any usage shebang script on $PATH" effect=read {
        alias ci
        alias init hide=#true
        alias completions-init hide=#true
        long_help #"""
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.
"""#
        flag --usage-bin help="Override the bin used for calling back to usage-cli" env=JDX_USAGE_BIN default=usage {
            long_help #"""
Override the bin used for calling back to usage-cli

You may need to set this if you have a different bin named "usage"
"""#
            arg <USAGE_BIN>
        }
        arg <SHELL> help="Shell to generate the init script for" {
            choices bash fish zsh
        }
    }
    cmd fig help="Generate Fig completion spec for Amazon Q / Fig" effect=read {
        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
            arg <FILE>
        }
        flag --out-file help="File path where the generated Fig spec will be saved, or \"-\" for stdout" effect=write {
            arg <OUT_FILE>
        }
        flag --spec help="Raw string spec input" overrides=--file required_unless=--file {
            arg <SPEC>
        }
        complete out_file type=path
    }
    cmd go help="Generate Go parse tables from a usage spec" effect=read {
        long_help #"""
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
"""#
        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
            arg <FILE>
        }
        flag "-o --out-file" help="File path where the generated Go source will be saved, or \"-\" for stdout" effect=write {
            arg <OUT_FILE>
        }
        flag "-p --package" help="Go package clause for the generated file (defaults to the spec's bin name)" {
            arg <PACKAGE>
        }
        flag --spec help="Raw string spec input" overrides=--file required_unless=--file {
            arg <SPEC>
        }
        complete out_file type=path
    }
    cmd json help="Outputs a usage spec in json format" effect=read {
        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
            arg <FILE>
        }
        flag --spec help="raw string spec input" overrides=--file required_unless=--file {
            arg <SPEC>
        }
        flag --view help="Render one spec-declared executable view" {
            arg <VIEW>
        }
    }
    cmd json-schema help="Generate a JSON Schema for a CLI's config file from its usage spec" effect=read {
        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" {
            arg <FILE>
        }
        flag --out-file help="Write the schema here instead of to stdout" effect=write {
            arg <OUT_FILE>
        }
        flag --spec help="raw string spec input" overrides=--file required_unless=--file {
            arg <SPEC>
        }
        flag --title help="The schema's title, shown by editors" {
            arg <TITLE>
        }
        flag --url help="Where the schema is published, for its `$id`" {
            arg <URL>
        }
        complete out_file type=path
    }
    cmd manpage help="Generate a manpage from a usage spec" effect=read {
        alias man
        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" required=#true {
            arg <FILE>
        }
        flag --view help="Render one spec-declared executable view" {
            arg <VIEW>
        }
        flag "-o --out-file" help="Output file path, or \"-\" for stdout (default)" effect=write {
            arg <OUT_FILE>
        }
        flag "-s --section" help="Manual section number (default: 1)" default="1" {
            long_help #"""
Manual section number (default: 1)

Common sections: - 1: User commands - 5: File formats - 7: Miscellaneous - 8: System administration commands
"""#
            arg <SECTION>
        }
        complete out_file type=path
    }
    cmd markdown help="Generate markdown documentation from usage specs" effect=read {
        alias md
        flag "-f --file" help="A usage spec taken in as a file, use \"-\" to read from stdin" required=#true {
            arg <FILE>
        }
        flag --view help="Render one spec-declared executable view" {
            arg <VIEW>
        }
        flag "-m --multi" help="Render each subcommand as a separate markdown file" conflicts=--out-file
        flag --html-encode help="Escape HTML in markdown"
        flag --out-dir help="Output markdown files to this directory (required when using --multi)" effect=write requires=--multi required_if=--multi {
            arg <OUT_DIR>
        }
        flag --out-file help="Output file path for single-file markdown generation, or \"-\" for stdout (default)" effect=write {
            arg <OUT_FILE>
        }
        flag --replace-pre-with-code-fences help="Replace `<pre>` tags with markdown code fences"
        flag --url-prefix help="Prefix to add to all URLs" {
            arg <URL_PREFIX>
        }
        complete out_dir type=dir
        complete out_file type=path
    }
    cmd sdk help="Generate a type-safe SDK from a usage spec" effect=write {
        flag "-f --file" help="A usage spec taken in as a file" {
            arg <FILE>
        }
        flag "-l --language" help="Target language for the SDK" required=#true {
            arg <LANGUAGE> {
                choices typescript python
            }
        }
        flag "-o --output" help="Output directory for generated SDK files" required=#true {
            arg <OUTPUT>
        }
        flag "-p --package-name" help="Override the package/module name (defaults to spec bin name)" {
            arg <PACKAGE_NAME>
        }
        flag --spec help="Raw string spec input" overrides=--file required_unless=--file {
            arg <SPEC>
        }
    }
}
cmd lint help="Lint a usage spec file for common issues" effect=read {
    flag "-f --format" help="Output format" default=text {
        arg <FORMAT> {
            choices {
                choice text
                choice json
            }
        }
    }
    flag "-W --warnings-as-errors" help="Treat warnings as errors"
    flag --sorted help="Also check that subcommands and flags are declared in sorted order" {
        long_help #"""
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.
"""#
    }
    arg <FILE> help="A usage spec file to lint, use \"-\" to read from stdin"
}
cmd mcp help="Serve a usage spec over the Model Context Protocol" effect=read {
    alias mcp-server
    long_help #"""
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`.
"""#
    flag "-f --file" help="Usage spec file (not \"-\": stdin is the MCP transport)" {
        arg <FILE>
    }
    flag "-s --spec" help="Raw string spec input" overrides=--file required_unless=--file {
        arg <SPEC>
    }
}
cmd powershell help="Execute a shell script using PowerShell" unknown_flags=value {
    long_help #"""
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.
"""#
    use shell
    arg <SCRIPT>
    arg "[ARGS]..." help="Arguments to pass to script" {
        long_help #"""
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.
"""#
    }
}
cmd sponsors help="Show the companies sponsoring usage and the jdx.dev open source tools" effect=read {
}
cmd zsh help="Execute a shell script using zsh" unknown_flags=value {
    long_help #"""
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.
"""#
    use shell
    arg <SCRIPT>
    arg "[ARGS]..." help="Arguments to pass to script" {
        long_help #"""
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.
"""#
    }
}
