Usage

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.

Rust framework

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.

Standalone CLI

Choose one installation method:

# mise
mise use -g usage

# Homebrew
brew install usage

# Cargo
cargo install usage-cli --locked

The 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.1

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

Contributing

See CONTRIBUTING.md for development setup, checks, and generated files.

Sponsors

Sponsored by

   

View all sponsors

Acknowledgements

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.

License

MIT. Third-party notices are in NOTICE.md.