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 = { package = "usage-rs", version = "6" }
use usage::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
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.