Define your CLI once. Generate the tools around it.
Usage is a portable KDL specification, a command-line utility, and a Rust framework. Describe commands, flags, arguments, and settings in one place, then use that definition for parsing, help, shell completions, Markdown docs, man pages, and typed clients.
Get started · Rust framework · Spec reference · CLI reference
| Your starting point | How Usage fits |
|---|---|
| A new Rust CLI | Derive a typed parser and exportable spec from structs and enums. |
| An existing CLI | Export a spec from your framework, or write KDL. |
| A script | Declare arguments in comments and let Usage parse them. |
| Code that calls a CLI | Generate a TypeScript or Python SDK. |
Applications can use usage-rs to derive a typed parser and a portable Usage
spec from the same Rust declaration:
[dependencies]
usage-rs = { version = "6" }use usage_rs::Cli;
#[derive(Cli)]
#[usage(bin = "example", version)]
struct App {
/// Print more detail.
#[usage(short = 'v', long, count)]
verbose: u8,
/// Files to process.
files: Vec<String>,
}
fn main() {
let app = App::parse();
// app.verbose and app.files are ready to use
}Usage has its own derive vocabulary: use #[usage(...)] on commands, fields,
and value variants. See the Rust framework guide
and clap migration guide for
the supported mappings and intentional differences.
Choose one installation method:
# mise
mise use -g usage
# Homebrew
brew install usage
# Cargo
cargo install usage-cli --lockedThe package is usage-cli; the executable is usage.
Other installation options.
With a spec saved as mycli.usage.kdl:
usage lint mycli.usage.kdl
usage generate completion zsh mycli --file mycli.usage.kdl --install
usage generate markdown --file mycli.usage.kdl --out-file reference.md
usage generate manpage --file mycli.usage.kdl --out-file mycli.1The generated shell scripts need usage at completion time. The Rust framework
can also provide completions directly
from your binary.
Follow the spec walkthrough for a complete example. The Go framework is a development preview and is not ready for adoption or testing.
See CONTRIBUTING.md for development setup, checks, and generated files.
Sponsored by
View all sponsors
Usage's design owes a great deal to clap. Its help output and diagnostic conventions make clap migrations familiar, while Usage's native derive attributes reflect its portable spec model. clap's license is reproduced in NOTICE.md.