--usage

Top-level metadata ​

kdl
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
long_version "1.0.0\ncommit abc123" // extended text for --version; -V uses version
author "nobody"      // the author of the CLI
license "MIT"        // SPDX license the CLI is released under
repository "https://github.com/me/myproj" // where the source lives

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

// examples (shown in markdown and manpage docs)
example "mycli --help" header="Getting help" help="Display help information"
example "mycli --version"

// 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 file="./my_overrides.usage.kdl" // include another spec, will be merged and override existing values

// a reusable set of flags, pulled into a command with `use` (see ./flagset.md)
flagset "common" { flag "-v --verbose" }

Multicall ​

multicall #true is clap's busybox-style applets: argv[0]'s basename selects a subcommand. The dispatcher names (name and bin) are skipped, so busybox ls still runs the ls applet. A symlink ls -> busybox does too, because the basename is ls. Path components and a trailing .exe are stripped.

kdl
name "busybox"
bin "busybox"
multicall #true
cmd "ls"
cmd "cat"

clap exposes this as Command::multicall / #[command(multicall = true)], and the bridge reads is_multicall_set.

Executable views ​

A view promotes a command path into a separately named executable surface. It is useful when one binary is installed under several names but an applet is more than multicall dispatch: its help, docs, and completions should begin at that command and may carry root globals.

kdl
name "Aube"
bin "aube"
flag "-v --verbose" global=#true
flag "--config <FILE>" global=#true
view "aubr" root="run" globals=#true
view "aubx" name="Aube Execute" root="dlx" {
  global "--config"
}
cmd "run"
cmd "dlx"

The first string is the stable view identifier and defaults both name and bin. root is a space-separated command path. globals=#true carries every root global; global children carry only the named root globals. Generators accept a view explicitly (usage g markdown --view aubr) or, for completions, select it when the requested binary matches the view's bin.

Repository ​

The URL of the CLI's source repository:

kdl
repository "https://github.com/jdx/mise"

This is the plain URL, not a template — the same value a Cargo.toml, package.json or pyproject.toml carries. It is available to documentation templates as repository, and it gives anything reading a spec out of context — a docs site, a registry, an agent handed a .usage.kdl file — a way to get back to the project.

It is deliberately separate from source_code_link_template below. That one is a per-command deep link with a placeholder, so recovering a repository URL from it means pattern-matching one forge's URL layout, and it is absent from most specs. Set both if you want both; neither implies the other.

A Rust CLI says this on the root, as #[usage(repository = "…")] — an expression, so env!("CARGO_PKG_REPOSITORY") keeps Cargo.toml the source of truth. clap has no equivalent concept, so a spec generated by clap_usage cannot carry it; there, declare it in an extra spec that is merged over the generated one.

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:

kdl
source_code_link_template #"""
{%- 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}}
"""#

A Rust CLI says this on the root too, as #[usage(source_code_link_template = r#"…"#)]. A raw string keeps every leading space, so write the template's lines unindented. As with repository, only a clap_usage-generated spec needs an extra spec merged over it.

Examples ​

Examples can be added at both the spec-level (top-level) and command-level to demonstrate CLI usage. Examples are displayed in generated markdown and manpage documentation.

Spec-Level Examples ​

Top-level examples showcase general usage of your CLI:

kdl
name "demo"
bin "demo"

example "demo --help" header="Getting help" help="Display help information for the demo command"
example "demo --version" header="Check version" help="Show the installed version of demo"

Command-Level Examples ​

Commands can also have their own examples (see cmd reference):

kdl
cmd "deploy" {
  flag "-e --environment <env>" help="Target environment"

  example "demo deploy -e prod" header="Basic deployment" help="Deploy to production environment"
  example "demo deploy -e staging --force" header="Force deployment"
}

Example Properties ​

Each example supports the following properties:

  • code (required): The command to demonstrate (first positional argument)
  • header (optional): A title for the example
  • help (optional): Description of what the example does
  • lang (optional): Programming language for syntax highlighting in markdown (defaults to empty)
MIT LicenseCopyright © 2026jdx.dev