One declaration for the whole CLI surface
Most command-line tools have several descriptions of the same interface. The parser knows the flags, the README has hand-written examples, a man page repeats the options, and every shell gets its own completion script. These copies drift. Usage puts commands, arguments, flags, environment variables, config files, outputs, and help into a KDL document that other tools can read.
The comparison to OpenAPI is useful. A Usage spec can generate Markdown, man pages, shell completions, JSON Schema, and client SDKs. It can also parse arguments for a program written in another language or scaffold definitions into supported frameworks. A binary may expose its own spec, allowing tooling to discover the interface instead of scraping --help output.
Recent additions make the spec especially interesting for coding agents. Commands can declare whether they read, write, or destroy state, and individual flags or arguments can raise that effect. Missing effect metadata means unknown, not safe. Output blocks can describe formats and exit codes. This is only descriptive metadata, not a security boundary, but it gives an agent or wrapper enough structure to ask before a destructive command and understand machine-readable output.
What happened when we ran it
We checked commit 7927115 in a fresh Debian container with 3 CPUs, 8 GB of RAM, Node 22, no secrets, and no elevated privileges. npm installation succeeded in 35 seconds, adding 274 packages and taking 351 MB on disk. The repository contained 790 files and about 237,173 lines of source.
The root npm package is for the VitePress documentation site. It has a docs:build command but no standard build target, so our harness skipped the build step. It also has no npm test target, so tests were skipped. This run did not compile or test the Rust workspace. That distinction matters because Usage itself is primarily Rust even though the sandbox selected the root Node package.
npm audit reported 5 known vulnerabilities: 3 high and 2 moderate. They belong to the installed Node dependency tree and should be assessed if you build or host the documentation. The repository also has a tests directory and 11 CI workflow files, which shows more engineering machinery than our npm-only path exercised. We cannot turn that presence into a passing test result from our run.
The Rust framework is capable and explicitly experimental
Rust developers can derive Cli on structs and enums, parse typed values, render help, and emit the same portable spec. Optional features cover completions, validation, configuration, response files, and test helpers. The project also documents a migration path from clap, including attribute replacements and differences in behavior.
The warning at the top of the Rust guide deserves attention: usage-rs is experimental, and point releases may break. This is not a small footnote for a parser, because argument behavior is part of a program's public interface. Pin the dependency, read release notes, and run CLI compatibility tests before updates.
Migration is easiest for clap applications already centered on derive macros. Programs using clap's runtime builder objects, ArgMatches, or CommandFactory need an architectural change because those pieces do not move into Usage's typed API. The guide also calls out differences in positional parsing, custom value parsing, default subcommands, and external subcommands. A compiler can catch type changes, but it cannot decide whether altered command behavior is acceptable to users.
Portability stops at unusual parsers and shell behavior
Usage aims at conventional GNU-style command lines. Its own specification guide says it cannot represent every possible CLI, and unusual option patterns may be rejected or warned about. Teams should model one real command before committing to a migration.
Shell completions are where portability meets messy host behavior. The project supports several shells, yet open reports document concrete edges. Issue #712 says generated zsh initialization can disturb fallback file completion and insert a literal asterisk. Issue #684 describes Fish completion initialization reading execute-only files on Fedora and printing permission errors. These reports do not erase the generator's value, but they make cross-shell testing part of adoption rather than an optional polish step.
For installation, users can choose mise, Cargo, Homebrew, or the Arch repository. Integrating the tool takes longer than installing it. A team must choose whether the KDL file or source-language declaration is authoritative, decide which generated artifacts are checked in, and add drift checks to CI. Without that ownership rule, one portable spec merely becomes another stale file.
Version 6.4.1 shipped alongside active issue work
The repository was pushed on August 26, 2026, and version 6.4.1 was released the same day. GitHub showed 29 open issues and pull requests combined, split into 24 issues and 5 pull requests by search. The release added terminal-aware help colors, adjusted negative-value parsing, hid marked commands from Markdown output, and lowered the published crates' minimum Rust version to 1.91.
Documentation is one of Usage's strongest reasons to try it. Separate guides cover the specification, CLI, Rust framework, Go binding, completions, migrations, and exact reference fields. The docs also state compatibility gaps instead of pretending every clap program or strange command syntax will fit.
Adopt Usage when the same CLI contract must serve humans, shells, SDK generators, and agents. For a small Rust binary that only needs parsing and help, clap remains the simpler default. Usage earns its extra concepts when generated artifacts and language-neutral introspection remove work you already have, not work you imagine having later.