# https://usage.jdx.dev/ llms-full.txt

<|firecrawl-page-1-lllmstxt|>
## CLI Usage Specifications
[Skip to content](https://usage.jdx.dev/#VPContent)

# Usage

A specification for CLIs

[Usage Specification](https://usage.jdx.dev/spec/)

[Usage CLI](https://usage.jdx.dev/cli/)

## Shell completions

Generate shell completions for any shell

## Documentation

Generate --help docs, markdown, and manpage documentation

## Scripts

Write scripts in bash or any other language with modern arg parsing, help, and completions

<|firecrawl-page-2-lllmstxt|>
## Shell Completion Scripts
[Skip to content](https://usage.jdx.dev/cli/completions#VPContent)

On this page

# Generating Completion Scripts [​](https://usage.jdx.dev/cli/completions\#generating-completion-scripts)

Usage can generate completion scripts for any shell. Here is an example for bash:

bash

```
usage g completion bash mycli -f ./mycli.usage.kdl > ~/.bash_completions/mycli.bash
source ~/.bash_completions/mycli.bash
mycli --<TAB>
```

zsh:

bash

```
usage g completion zsh mycli -f ./mycli.usage.kdl > ~/.zsh_completions/_mycli
source ~/.zsh_completions/_mycli
mycli --<TAB>
```

fish:

bash

```
usage g completion fish mycli -f ./mycli.usage.kdl > ~/.config/fish/completions/mycli.fish
mycli --<TAB>
```

fig/Amazon Q:

bash

```
usage g fig -f ./mycli.usage.kdl > ./mycli.fig.ts
mycli --<TAB>
```

INFO

Usage CLI is a runtime dependency for the generated completion scripts. Your users will need to have `usage` installed in order for the completion scripts to work.

New shells should be easy to add because the logic around completions is mostly handled by the Usage CLI. Typically, completion scripts will call usage like this to fetch completion choices (cword is the index of the current word):

bash

```
$ usage complete-word --file ./mycli.usage.kdl -- mycli cmd1 cmd2 --f
--force
--file
```

## Completions for `usage` CLI itself [​](https://usage.jdx.dev/cli/completions\#completions-for-usage-cli-itself)

Completions for the `usage` CLI itself can be generated with one of the following commands:

bash

```
usage --completions bash > /etc/bash_completion.d/usage
usage --completions zsh > /usr/share/zsh/site-functions/_usage
usage --completions fish > ~/.config/fish/completions/usage.fish
```

<|firecrawl-page-3-lllmstxt|>
## CLI Installation Guide
[Skip to content](https://usage.jdx.dev/cli/#VPContent)

On this page

# CLI [​](https://usage.jdx.dev/cli/\#cli)

## Installation [​](https://usage.jdx.dev/cli/\#installation)

### [mise-en-place](https://mise.jdx.dev/) [​](https://usage.jdx.dev/cli/\#mise-en-place)

sh

```
mise use -g usage
```

### Cargo [​](https://usage.jdx.dev/cli/\#cargo)

sh

```
cargo install usage-cli
```

You can also use [`cargo-binstall`](https://github.com/cargo-bins/cargo-binstall) to install quicker:

sh

```
cargo binstall usage-cli
```

### Homebrew [​](https://usage.jdx.dev/cli/\#homebrew)

sh

```
brew install usage
```

### Arch Linux [​](https://usage.jdx.dev/cli/\#arch-linux)

usage is available in [Extra](https://archlinux.org/packages/extra/x86_64/usage/)

sh

```
pacman -S usage
```

<|firecrawl-page-4-lllmstxt|>
## Generating Manpages
[Skip to content](https://usage.jdx.dev/cli/manpages#VPContent)

Return to top

# Generating Manpages [​](https://usage.jdx.dev/cli/manpages\#generating-manpages)

Usage CLI can generate manpages from a Usage definition. Here is an example:

bash

```
$ usage g manpage -f ./mycli.usage.kdl > /usr/share/man/man1/mycli.1
$ man mycli
mycli(1)                    General Commands Manual                   mycli(1)

NAME
       mycli - description

SYNOPSIS
       mycli [-h|--help] [-V|--version] <subcommands>

DESCRIPTION
       ...

OPTIONS
       -h, --help
              Print help (see a summary with '-h')
...
```

<|firecrawl-page-5-lllmstxt|>
## Markdown Documentation Generation
[Skip to content](https://usage.jdx.dev/cli/markdown#VPContent)

Return to top

# Generating Markdown Documentation [​](https://usage.jdx.dev/cli/markdown\#generating-markdown-documentation)

Usage CLI can generate markdown documentation from a Usage definition either into a single file, or a directory.

Single file (will be injected in the comment):

sh

```
$ cat <<EOF > ./README.md
# My CLI
## Header
...
## CLI Commands
<!-- usage:start -->
## Footer
...
EOF
$ usage g markdown -f ./mycli.usage.kdl --inject README.md
$ cat README.md
# My CLI
## Header
## CLI Commands
<!-- usage:start -->
### `mycli config add KEY VALUE`
### `mycli config remove NAME`
<!-- usage:end   -->
## Footer
```

Multiple files:

sh

```
$ usage g markdown -mf ./mycli.usage.kdl --out-dir ./docs
$ tree ./docs
docs
├── config
│   ├── add.md
│   ├── list.md
│   └── remove.md
├── index.md
└── update.md
```

<|firecrawl-page-6-lllmstxt|>
## Bash Script Usage
[Skip to content](https://usage.jdx.dev/cli/reference/bash#VPContent)

On this page

# `usage bash` [​](https://usage.jdx.dev/cli/reference/bash\#usage-bash)

- **Usage**: `usage bash [-h] [--help] <SCRIPT> [ARGS]…`
- **Source code**: [`cli/src/cli/bash.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/bash.rs)

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

## Arguments [​](https://usage.jdx.dev/cli/reference/bash\#arguments)

### `<SCRIPT>` [​](https://usage.jdx.dev/cli/reference/bash\#script)

### `[ARGS]…` [​](https://usage.jdx.dev/cli/reference/bash\#args)

arguments to pass to script

## Flags [​](https://usage.jdx.dev/cli/reference/bash\#flags)

### `-h` [​](https://usage.jdx.dev/cli/reference/bash\#h)

show help

### `--help` [​](https://usage.jdx.dev/cli/reference/bash\#help)

show help

<|firecrawl-page-7-lllmstxt|>
## Complete Word Command
[Skip to content](https://usage.jdx.dev/cli/reference/complete-word#VPContent)

On this page

# `usage complete-word` [​](https://usage.jdx.dev/cli/reference/complete-word\#usage-complete-word)

- **Usage**: `usage complete-word [FLAGS] [WORDS]…`
- **Aliases**: `cw`
- **Source code**: [`cli/src/cli/complete-word.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/complete-word.rs)

## Arguments [​](https://usage.jdx.dev/cli/reference/complete-word\#arguments)

### `[WORDS]…` [​](https://usage.jdx.dev/cli/reference/complete-word\#words)

user's input from the command line

## Flags [​](https://usage.jdx.dev/cli/reference/complete-word\#flags)

### `--shell <SHELL>` [​](https://usage.jdx.dev/cli/reference/complete-word\#shell-shell)

**Choices:**

- `bash`
- `fish`
- `zsh`

### `-f --file <FILE>` [​](https://usage.jdx.dev/cli/reference/complete-word\#f-file-file)

usage spec file or script with usage shebang

### `-s --spec <SPEC>` [​](https://usage.jdx.dev/cli/reference/complete-word\#s-spec-spec)

raw string spec input

### `--cword <CWORD>` [​](https://usage.jdx.dev/cli/reference/complete-word\#cword-cword)

current word index

<|firecrawl-page-8-lllmstxt|>
## Usage Fish Command
[Skip to content](https://usage.jdx.dev/cli/reference/fish#VPContent)

On this page

# `usage fish` [​](https://usage.jdx.dev/cli/reference/fish\#usage-fish)

- **Usage**: `usage fish [-h] [--help] <SCRIPT> [ARGS]…`
- **Source code**: [`cli/src/cli/fish.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/fish.rs)

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

## Arguments [​](https://usage.jdx.dev/cli/reference/fish\#arguments)

### `<SCRIPT>` [​](https://usage.jdx.dev/cli/reference/fish\#script)

### `[ARGS]…` [​](https://usage.jdx.dev/cli/reference/fish\#args)

arguments to pass to script

## Flags [​](https://usage.jdx.dev/cli/reference/fish\#flags)

### `-h` [​](https://usage.jdx.dev/cli/reference/fish\#h)

show help

### `--help` [​](https://usage.jdx.dev/cli/reference/fish\#help)

show help

<|firecrawl-page-9-lllmstxt|>
## Generate Command Reference
[Skip to content](https://usage.jdx.dev/cli/reference/generate#VPContent)

On this page

# `usage generate` [​](https://usage.jdx.dev/cli/reference/generate\#usage-generate)

- **Usage**: `usage generate <SUBCOMMAND>`
- **Aliases**: `g`
- **Source code**: [`cli/src/cli/generate.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate.rs)

## Subcommands [​](https://usage.jdx.dev/cli/reference/generate\#subcommands)

- [`usage generate completion [FLAGS] <SHELL> <BIN>`](https://usage.jdx.dev/cli/reference/generate/completion)
- [`usage generate fig [FLAGS]`](https://usage.jdx.dev/cli/reference/generate/fig)
- [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](https://usage.jdx.dev/cli/reference/generate/json)
- [`usage generate markdown <FLAGS>`](https://usage.jdx.dev/cli/reference/generate/markdown)

<|firecrawl-page-10-lllmstxt|>
## CLI Completion Generation
[Skip to content](https://usage.jdx.dev/cli/reference/generate/completion#VPContent)

On this page

# `usage generate completion` [​](https://usage.jdx.dev/cli/reference/generate/completion\#usage-generate-completion)

- **Usage**: `usage generate completion [FLAGS] <SHELL> <BIN>`
- **Aliases**: `c`
- **Source code**: [`cli/src/cli/generate/completion.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/completion.rs)

## Arguments [​](https://usage.jdx.dev/cli/reference/generate/completion\#arguments)

### `<SHELL>` [​](https://usage.jdx.dev/cli/reference/generate/completion\#shell)

**Choices:**

- `bash`
- `fish`
- `zsh`

### `<BIN>` [​](https://usage.jdx.dev/cli/reference/generate/completion\#bin)

The CLI which we're generates completions for

## Flags [​](https://usage.jdx.dev/cli/reference/generate/completion\#flags)

### `--cache-key <CACHE_KEY>` [​](https://usage.jdx.dev/cli/reference/generate/completion\#cache-key-cache-key)

A cache key to use for storing the results of calling the CLI with --usage-cmd

### `-f --file <FILE>` [​](https://usage.jdx.dev/cli/reference/generate/completion\#f-file-file)

A .usage.kdl spec file to use for generating completions

### `--usage-bin <USAGE_BIN>` [​](https://usage.jdx.dev/cli/reference/generate/completion\#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>` [​](https://usage.jdx.dev/cli/reference/generate/completion\#usage-cmd-usage-cmd)

A command which generates a usage spec e.g.: `mycli --usage` or `mycli completion usage` Defaults to "$bin --usage"

### `--include-bash-completion-lib` [​](https://usage.jdx.dev/cli/reference/generate/completion\#include-bash-completion-lib)

Include [https://github.com/scop/bash-completion](https://github.com/scop/bash-completion)

This is required for usage completions to work in bash, but the user may already provide it

<|firecrawl-page-11-lllmstxt|>
## Generate Fig Command
[Skip to content](https://usage.jdx.dev/cli/reference/generate/fig#VPContent)

On this page

# `usage generate fig` [​](https://usage.jdx.dev/cli/reference/generate/fig\#usage-generate-fig)

- **Usage**: `usage generate fig [FLAGS]`
- **Source code**: [`cli/src/cli/generate/fig.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/fig.rs)

## Flags [​](https://usage.jdx.dev/cli/reference/generate/fig\#flags)

### `-f --file <FILE>` [​](https://usage.jdx.dev/cli/reference/generate/fig\#f-file-file)

A usage spec taken in as a file

### `--spec <SPEC>` [​](https://usage.jdx.dev/cli/reference/generate/fig\#spec-spec)

raw string spec input

### `--out-file <OUT_FILE>` [​](https://usage.jdx.dev/cli/reference/generate/fig\#out-file-out-file)

File on where to save the generated Fig spec

<|firecrawl-page-12-lllmstxt|>
## Generate JSON Usage
[Skip to content](https://usage.jdx.dev/cli/reference/generate/json#VPContent)

On this page

# `usage generate json` [​](https://usage.jdx.dev/cli/reference/generate/json\#usage-generate-json)

- **Usage**: `usage generate json [-f --file <FILE>] [--spec <SPEC>]`
- **Source code**: [`cli/src/cli/generate/json.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/json.rs)

Outputs a usage spec in json format

## Flags [​](https://usage.jdx.dev/cli/reference/generate/json\#flags)

### `-f --file <FILE>` [​](https://usage.jdx.dev/cli/reference/generate/json\#f-file-file)

A usage spec taken in as a file

### `--spec <SPEC>` [​](https://usage.jdx.dev/cli/reference/generate/json\#spec-spec)

raw string spec input

<|firecrawl-page-13-lllmstxt|>
## Markdown Generation CLI
[Skip to content](https://usage.jdx.dev/cli/reference/generate/markdown#VPContent)

On this page

# `usage generate markdown` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#usage-generate-markdown)

- **Usage**: `usage generate markdown <FLAGS>`
- **Aliases**: `md`
- **Source code**: [`cli/src/cli/generate/markdown.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/generate/markdown.rs)

## Flags [​](https://usage.jdx.dev/cli/reference/generate/markdown\#flags)

### `-f --file <FILE>` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#f-file-file)

A usage spec taken in as a file

### `-m --multi` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#m-multi)

Render each subcommand as a separate markdown file

### `--url-prefix <URL_PREFIX>` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#url-prefix-url-prefix)

Prefix to add to all URLs

### `--html-encode` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#html-encode)

Escape HTML in markdown

### `--replace-pre-with-code-fences` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#replace-pre-with-code-fences)

### `--out-dir <OUT_DIR>` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#out-dir-out-dir)

Output markdown files to this directory

### `--out-file <OUT_FILE>` [​](https://usage.jdx.dev/cli/reference/generate/markdown\#out-file-out-file)

<|firecrawl-page-14-lllmstxt|>
## CLI Usage Reference
[Skip to content](https://usage.jdx.dev/cli/reference/#VPContent)

On this page

# `usage` [​](https://usage.jdx.dev/cli/reference/\#usage)

**Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`

**Version**: 2.2.2

- **Usage**: `usage [--usage-spec] [COMPLETIONS] <SUBCOMMAND>`

## Arguments [​](https://usage.jdx.dev/cli/reference/\#arguments)

### `[COMPLETIONS]` [​](https://usage.jdx.dev/cli/reference/\#completions)

Outputs completions for the specified shell for completing the `usage` CLI itself

## Flags [​](https://usage.jdx.dev/cli/reference/\#flags)

### `--usage-spec` [​](https://usage.jdx.dev/cli/reference/\#usage-spec)

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

## Subcommands [​](https://usage.jdx.dev/cli/reference/\#subcommands)

- [`usage complete-word [FLAGS] [WORDS]…`](https://usage.jdx.dev/cli/reference/complete-word)
- [`usage generate <SUBCOMMAND>`](https://usage.jdx.dev/cli/reference/generate)
- [`usage generate completion [FLAGS] <SHELL> <BIN>`](https://usage.jdx.dev/cli/reference/generate/completion)
- [`usage generate fig [FLAGS]`](https://usage.jdx.dev/cli/reference/generate/fig)
- [`usage generate json [-f --file <FILE>] [--spec <SPEC>]`](https://usage.jdx.dev/cli/reference/generate/json)
- [`usage generate markdown <FLAGS>`](https://usage.jdx.dev/cli/reference/generate/markdown)
- [`usage bash [-h] [--help] <SCRIPT> [ARGS]…`](https://usage.jdx.dev/cli/reference/bash)
- [`usage fish [-h] [--help] <SCRIPT> [ARGS]…`](https://usage.jdx.dev/cli/reference/fish)
- [`usage zsh [-h] [--help] <SCRIPT> [ARGS]…`](https://usage.jdx.dev/cli/reference/zsh)

<|firecrawl-page-15-lllmstxt|>
## Zsh Usage Reference
[Skip to content](https://usage.jdx.dev/cli/reference/zsh#VPContent)

On this page

# `usage zsh` [​](https://usage.jdx.dev/cli/reference/zsh\#usage-zsh)

- **Usage**: `usage zsh [-h] [--help] <SCRIPT> [ARGS]…`
- **Source code**: [`cli/src/cli/zsh.rs`](https://github.com/jdx/usage/blob/main/cli/src/cli/zsh.rs)

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

## Arguments [​](https://usage.jdx.dev/cli/reference/zsh\#arguments)

### `<SCRIPT>` [​](https://usage.jdx.dev/cli/reference/zsh\#script)

### `[ARGS]…` [​](https://usage.jdx.dev/cli/reference/zsh\#args)

arguments to pass to script

## Flags [​](https://usage.jdx.dev/cli/reference/zsh\#flags)

### `-h` [​](https://usage.jdx.dev/cli/reference/zsh\#h)

show help

### `--help` [​](https://usage.jdx.dev/cli/reference/zsh\#help)

show help

<|firecrawl-page-16-lllmstxt|>
## Usage CLI Scripts
[Skip to content](https://usage.jdx.dev/cli/scripts#VPContent)

On this page

# Usage Scripts [​](https://usage.jdx.dev/cli/scripts\#usage-scripts)

Scripts can be used with the Usage CLI to display help, powerful arg parsing, and autocompletion in any language. For this to work, we add comments to the script that describe the flags and arguments that the script accepts. Here is an example in bash:

bash

```
#!/usr/bin/env -S usage bash
#USAGE flag "-f --force" help="Overwrite existing <file>"
#USAGE flag "-u --user <user>" help="User to run as"
#USAGE arg "<file>" help="The file to write" default="file.txt"

if [ "$usage_force" = "true" ]; then
  rm -f "$usage_file"
fi
if [ -n "$usage_user" ]; then
  echo "Hello, $usage_user" >> "$usage_file"
else
  echo "Hello, world" >> "$usage_file"
fi
```

Assuming this script was located at `./mycli`, it could be used like this:

bash

```
$ ./mycli --help
Usage: mycli [flags] [args]
...
$ ./mycli -f --user=alice output.txt
$ cat output.txt
Hello, alice
```

For languages that use `//` for comments, like JavaScript, you can use `//USAGE` comments:

js

```
#!/usr/bin/env -S usage node
//USAGE flag "-f --force" help="Overwrite existing <file>"
//USAGE flag "-u --user <user>" help="User to run as"
//USAGE arg "<file>" help="The file to write" default="file.txt"

const fs = require("fs");

const { usage_user, usage_force, usage_file } = process.env;

if (usage_force === "true") {
  fs.rmSync(usage_file, { force: true });
}

const user = usage_user ?? "world";
fs.appendFileSync(usage_file, `Hello, ${user}\n`);
```

## Short Flag Chaining [​](https://usage.jdx.dev/cli/scripts\#short-flag-chaining)

Short flag chaining allows you to combine multiple single-character flags into a single argument. This can make command-line usage more concise and easier to type.

For example, consider the following script:

bash

```
#!/usr/bin/env -S usage bash
#USAGE flag "-a" help="Option A"
#USAGE flag "-b" help="Option B"
#USAGE flag "-c" help="Option C"

if [ "$usage_a" = "true" ]; then
  echo "Option A is set"
fi
if [ "$usage_b" = "true" ]; then
  echo "Option B is set"
fi
if [ "$usage_c" = "true" ]; then
  echo "Option C is set"
fi
```

Assuming this script was located at `./mycli`, it could be used like this:

bash

```
$ ./mycli -abc
Option A is set
Option B is set
Option C is set
```

In this example, the `-a`, `-b`, and `-c` flags are combined into a single `-abc` argument, enabling all three options at once.

## Shell Escaping [​](https://usage.jdx.dev/cli/scripts\#shell-escaping)

### `var=\#true` [​](https://usage.jdx.dev/cli/scripts\#var-true)

When using `var=#true`, the value will be a single string (because that's all env vars can do) delimited by spaces. If an arg itself has a space, then it will have quotes around it. This logic is handled by [`shell_words::join()`](https://docs.rs/shell-words/latest/shell_words/fn.join.html). For now, this is not customizable behavior. It would be possible to support [alternatives](https://github.com/jdx/usage/issues/189) though.

<|firecrawl-page-17-lllmstxt|>
## CLI Tool Specification
[Skip to content](https://usage.jdx.dev/spec/#VPContent)

On this page

# Usage Specification [​](https://usage.jdx.dev/spec/\#usage-specification)

Usage is a spec and CLI for defining CLI tools. Arguments, flags, environment variables, and config files can all be defined in a Usage spec. It can be thought of like [OpenAPI (swagger)](https://www.openapis.org/) for CLIs. Here are some potential reasons for defining your CLI with a Usage spec:

- Generate autocompletion scripts
- Generate markdown documentation
- Generate man pages
- Use an advanced arg parser in any language
- Scaffold one spec into different CLI frameworks—even different languages
- \[coming soon\] Host your CLI documentation on usage.sh

## Example Usage Spec [​](https://usage.jdx.dev/spec/\#example-usage-spec)

Usage specs are written in [kdl](https://kdl.dev/) which is a newer document language that sort of combines the best of XML and JSON. Here is a basic example CLI definition:

sh

```
# optional metadata
name "My CLI"        # a friendly name for the CLI
bin "mycli"          # the name of the binary
about "some help"    # a short description of the CLI
version "1.0.0"      # the version of the CLI
author "nobody"      # the author of the CLI
license "MIT"        # license the CLI is released under

# a standard flag
flag "-f --force"   help="Always do the thing"
flag "-v --version" help="Print the CLI version"
flag "-h --help"    help="Print the CLI help"

# a flag that takes a value
flag "-u --user <user>" help="User to run as"

arg "<dir>"  help="The directory to use" # required positional argument
arg "[file]" help="The file to read"     # optional positional argument
```

And here is an example CLI with nested subcommands:

sh

```
flag "-v --verbose" "Enable verbose logging" global=#true count=#true
flag "-q --quiet" "Enable quiet logging" global=#true
flag "-u --user <user>" help="User to run as"

cmd "update" help="Update the CLI"
cmd "config" help="Manage the CLI config" {
  # "set" is an alias for "add"
  cmd "add" "Add/set a config" {
    alias "set"
    arg "<key>" help="The key for the config"
    arg "<value>" help="The new config value"
    flag "-f --force" help="Overwrite existing config"
  }
  cmd "remove" help="Remove a thing" {
    alias "rm"
    alias "delete" hide=#true # hide alias from docs and completions
    arg "<name>" help="The name of the thing"
  }
  cmd "list" help="List all things"
}
cmd "version" help="Print the CLI version"
cmd "help" help="Print the CLI help"
```

Flags/args can be backed by config files, environment variables, or defaults:

sh

```
config_file ".mycli.toml" findup=#true
flag "-u --user <user>" help="User to run as" env="MYCLI_USER" config="settings.user" default="admin"
```

The priority over which is used (CLI flag, env var, config file, default) is the order which they are defined, so in this example it will be "CLI flag > env var > config file > default".

## Compatibility [​](https://usage.jdx.dev/spec/\#compatibility)

Usage is not designed to model every possible CLI. It's generally designed for CLIs that follow standard GNU-style options. While it is not high priority, adding support for CLIs that differ from the standard may be allowed. As an example, some CLIs may accept multiple options on a flag: `--flag option1 option2`. This is poor design as it's unclear to the user if "option2" is another positional arg or not. What we will likely do for behaviors like this is allow it, but show a warning that it is not recommended.

## CLI Framework Developers [​](https://usage.jdx.dev/spec/\#cli-framework-developers)

You could think of Usage like an LSP (Language Server Protocol) for CLIs.

Those building CLI frameworks can really benefit from Usage. Rather than building features like autocompletion for every shell, just output a Usage definition and use the Usage CLI to generate autocompletion scripts for all of the shells it supports.

<|firecrawl-page-18-lllmstxt|>
## Integrations for Usage
[Skip to content](https://usage.jdx.dev/spec/integrations#VPContent)

On this page

# Integrations [​](https://usage.jdx.dev/spec/integrations\#integrations)

Here are various ways to integrate usage into your project such as with your CLI parsing library to have it generate a usage spec from the parser configuration.

## `clap` for Rust CLIs [​](https://usage.jdx.dev/spec/integrations\#clap-for-rust-clis)

[`clap_usage`](https://crates.io/crates/clap_usage) is a library for generating usage spec from a CLI built with [`clap`](https://crates.io/crates/clap).

<|firecrawl-page-19-lllmstxt|>
## Argument Reference Guide
[Skip to content](https://usage.jdx.dev/spec/reference/arg#VPContent)

Return to top

# `arg` [​](https://usage.jdx.dev/spec/reference/arg\#arg)

sh

```
arg "<file>"                             # positional arg, completed as a filename
arg "<dir>"                              # positional arg, completed as a directory
arg "[file]"                             # optional positional arg
arg "<file>" default="file.txt"          # default value for arg
arg "<file>" parse="mycli parse-file {}" # parse arg value with external command

arg "[file]" var=#true # multiple args can be passed (e.g. mycli file1 file2 file3) (0 or more)
arg "<file>" var=#true # multiple args can be passed (e.g. mycli file1 file2 file3) (1 or more)
arg "<file>" var=#true var_min=3 # at least 3 args must be passed
arg "<file>" var=#true var_max=3 # up to 3 args can be passed

arg "<shell>" {
  choices "bash" "zsh" "fish" # <shell> must be one of the choices
}

arg "<file>" long_help="longer help for --help (as oppoosed to -h)"

# double-dash behavior
arg "<file>" double_dash="required" # arg must be passed after a double dash (e.g. mycli -- file.txt)
arg "<file>" double_dash="optional" # arg may be passed after a double dash (e.g. mycli -- file.txt or mycli file.txt)
arg "<file>..." double_dash="automatic" # once arg is passed, behave as if a double dash was passed (e.g. mycli file.txt --filewithdash)
```

<|firecrawl-page-20-lllmstxt|>
## Command Reference Guide
[Skip to content](https://usage.jdx.dev/spec/reference/cmd#VPContent)

On this page

# `cmd` [​](https://usage.jdx.dev/spec/reference/cmd\#cmd)

sh

```
# aliases
cmd "config" help="Manage the CLI config" {
  alias "cfg" "cf" "cg"  # aliases for the command
  alias "conf" hide=#true # hide alias from docs and completions
}

cmd "config" hide=#true # hide command from docs and completions
cmd "config" subcommand_required=#true # subcommand is not optional

# these are shown under -h
cmd "config" before_help="shown before the command"
cmd "config" help="short description"
cmd "config" after_help="shown after the command"

# these are shown under --help
# all help fields can be either inline params or separate nodes like
# below for the *_long_help fields. Typically when a lot of space is needed
# it's cleaner to use separate nodes.
cmd "config" {
  before_long_help "shown before the command"
  long_help "longer description"
  after_long_help "shown after the command"
}

cmd "list" {
  example "Basic usage" r#"
    $ mycli list
    FRUIT  COLOR
    apple  red
    banana yellow
  "#
  example "JSON output" r#"
    $ mycli list --json
    [\
      {"FRUIT": "apple", "COLOR": "red"},\
      {"FRUIT": "banana", "COLOR": "yellow"}\
    ]
  "#
}
```

## Mounting dynamic commands [​](https://usage.jdx.dev/spec/reference/cmd\#mounting-dynamic-commands)

A usage spec can define a command to run which emits extra usage spec which will be merged into the cmd. For example, assume a CLI named `mycli` has a command `run` which executes a set of tasks, those tasks are themselves commands which have their own sets of args/flags dynamically generated. To support this, create a hidden command like `mycli mount-usage-tasks` which emits usage spec for the tasks. Then, create a `mount` on the `run` command. Here is the static usage spec for the `mycli` CLI as described:

sh

```
cmd "mount-usage-tasks" hide=#true
cmd "run" {
	mount run="mycli mount-usage-tasks"
}
```

Calling `mycli mount-usage-tasks` would emit something like this:

sh

```
cmd "task1" {
  arg "arg1" help="task1 arg1"
  flag "flag1" help="task1 flag1"
}
cmd "task2" {
  arg "arg1" help="task2 arg1"
  flag "flag1" help="task2 flag1"
}
```

Now when using completion with usage, if the user types `mycli run <tab><tab>`, usage will then call `mycli mount-usage-tasks` and merge the emitted usage into the `run` command and display the task commands as if they were statically defined in the usage spec.

<|firecrawl-page-21-lllmstxt|>
## Completion Command Reference
[Skip to content](https://usage.jdx.dev/spec/reference/complete#VPContent)

On this page

# `complete` [​](https://usage.jdx.dev/spec/reference/complete\#complete)

sh

```
# use a custom completion command for all args named "plugin"
complete "plugin" run="mycli plugins list"
```

## Descriptions [​](https://usage.jdx.dev/spec/reference/complete\#descriptions)

If you set `descriptions=#true`, you can provide descriptions for the completions:

sh

```
complete "plugin" run="mycli plugins list" descriptions=#true
```

Results will be split on ":" with the first part being the completion value and the second part being the description, e.g.:

```
user:User's full name
port:Port number
```

":" can be escaped with a backslash.

## Templates [​](https://usage.jdx.dev/spec/reference/complete\#templates)

The run can be customized with [tera](https://keats.github.io/tera/) templates. The following values are available:

- `words`: A list of all words currently in the prompt. Individual words can be accessed `words[1]`
- `CURRENT`: The index of the word currently being typed, combine with `words` to get the current word e.g. `words[CURRENT]`.
- `PREV`: The index of the previous word in the prompt (CURRENT-1), combine with `words` to get the previous word e.g. `words[PREV]`.

Example of completing the second argument based on the first:

sh

```
arg "<module>"
arg "<controller>"
complete "module" run="ls modules"
complete "controller" run="ls modules/{{words[PREV]}}/controllers"
```

Example of using multiple words (one, two, three) for the completions of the forth argument:

sh

```
arg "<one>"
arg "<two>"
arg "<three>"
arg "<four>"
complete "four" run="echo {{ words | slice(start=-4) | join(sep='\"\n\"') }}"
```

Here we just use simple commands like `ls` and `echo` but these words could be passed to any command.

<|firecrawl-page-22-lllmstxt|>
## Configuration Reference Guide
[Skip to content](https://usage.jdx.dev/spec/reference/config#VPContent)

On this page

# Configuration [​](https://usage.jdx.dev/spec/reference/config\#configuration)

The default priority for configuration properties in usage is the following:

- CLI flag (e.g. `--user alice`)
- Environment variable (e.g. `MYCLI_USER=alice`)
- Config file (e.g. `~/.mycli.toml`)
- Default value

## Environment Variables [​](https://usage.jdx.dev/spec/reference/config\#environment-variables)

TODO

## Config Files [​](https://usage.jdx.dev/spec/reference/config\#config-files)

kdl

```
config {
    // system
    file "/etc/mycli.toml"
    file "/etc/mycli.json"

    // global
    file "~/.config/mycli.toml"
    file "~/.config/mycli.json"

    // local
    file ".config/mycli.toml" findup=#true
    file ".config/mycli.json" findup=#true
    file ".mycli.dist.toml" findup=#true
    file ".mycli.dist.json" findup=#true
    file ".mycli.toml" findup=#true
    file ".mycli.json" findup=#true
    file ".myclirc" findup=#true format="ini"

    // e.g.: .mycli.dev.toml, .mycli.prod.toml
    file ".mycli.$MYCLI_ENV.toml" findup=#true

    default "user" "admin"
    default "work_dir" "/tmp"
    default "yes" false

    alias "user" "username"
}
```

## Alias Config Keys [​](https://usage.jdx.dev/spec/reference/config\#alias-config-keys)

Config keys can be aliased to other keys. This is useful for backwards compatibility.

kdl

```
config_file ".mycli.toml" findup=#true
config_alias "user" "username"
```

<|firecrawl-page-23-lllmstxt|>
## Flag Definition Reference
[Skip to content](https://usage.jdx.dev/spec/reference/flag#VPContent)

Return to top

# `flag` [​](https://usage.jdx.dev/spec/reference/flag\#flag)

sh

```
flag "-u --user <user>" # one way to define a flag
flag "--user" { # another way to define the same flag
  alias "-u"
  arg "<user>"
}
flag "--user" { alias "-u" hide=#true } # hide alias from docs and completions

flag "-f --force" global=#true           # global can be set on any subcommand
flag "--file <file>" default="file.txt" # default value for flag
flag "-v --verbose" count=#true          # instead of true/false $usage_verbose is # of times
                                        # flag was used (e.g. -vvv = 3)

flag "--color" negate="--no-color" default=#true  # $usage_color=#true by default
                                                 # --no-color will set $usage_color=#false

flag "--color" env="MYCLI_COLOR" # flag can be backed by an env var
flag "--color" config="ui.color" # flag can be backed by a config file

flag "--file <file>"  # args named "<file>" will be completed as files
flag "--dir <dir>"    # args named "<dir>" will be completed as directories

flag "--file <file>" required_if="--dir"     # if --dir is set, --file must also be set
flag "--file <file>" required_unless="--dir" # either --file or --dir must be present
flag "--file <file>" overrides="--stdin"     # if --file is set, previous --stdin will be ignored

flag "--shell <shell>" {
  choices "bash" "zsh" "fish" # <shell> must be one of the choices
}

flag "--file <file>" long_help="longer help for --help (as oppoosed to -h)"
# this is equivalent to the above but preferred when a lot of space is needed
flag "--file <file>" {
  long_help r#"longer help for --help (as oppoosed to -h)
   even
   more
   text
   "#
}
```

<|firecrawl-page-24-lllmstxt|>
## CLI Usage Specification
[Skip to content](https://usage.jdx.dev/spec/reference/#VPContent)

On this page

# Top-level metadata [​](https://usage.jdx.dev/spec/reference/\#top-level-metadata)

sh

```
min_usage_version "1.0.0" # the minimum version of usage this CLI supports
                          # you want this at the top

name "My CLI"        # a friendly name for the CLI
bin "mycli"          # the name of the binary
version "1.0.0"      # the version of the CLI
author "nobody"      # the author of the CLI
license "MIT"        # SPDX license the CLI is released under

# help for -h
before_help "before about"
about "some help"
after_help "after about"

# help for --help
before_long_help "before about"
long_about "longer help"
after_long_help "after about"
example "mycli --help"

# render a link to the source code in markdown docs
source_code_link_template "https://github.com/me/myproj/blob/main/src/cli/{{path}}.rs"

include "./my_overrides.usage.kdl" # include another spec, will be merged and override existing values
```

## Source Code Link Template [​](https://usage.jdx.dev/spec/reference/\#source-code-link-template)

This is a tera template that can be used to customize the path for markdown documentation. For example, in mise I use the following to convert filenames to snake case:

sh

```
source_code_link_template r#"
{%- set path = path | replace(from='-', to='_') -%}
{%- if cmd.subcommands | length > 0 -%}
{%- set path = path | split(pat="/") | slice(end=1) | concat(with="mod.rs") | join(sep="/") -%}
{%- else -%}
{%- set path = path ~ ".rs" -%}
{%- endif -%}
https://github.com/jdx/mise/blob/main/src/cli/{{path}}"#
```