gem-hunter

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

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

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.

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