Usage is a powerful specification and command-line interface designed to simplify the definition, documentation, and distribution of CLI tools. Much like OpenAPI for web APIs, Usage allows developers to define CLI structures, including arguments, flags, environment variables, and configuration files, in a single, human-readable KDL format. By centralizing the definition of a CLI, developers can eliminate redundant tasks and maintain consistency across documentation, shell completions, and client SDKs.

Usage works by acting as a source of truth for your command-line application. Once a CLI is defined using a Usage spec, the Usage CLI can automate the generation of essential development artifacts. This includes auto-completion scripts for major shells like bash, zsh, fish, PowerShell, and nushell, ensuring a seamless experience for end-users. Additionally, Usage can automatically generate manpages, markdown documentation, and even type-safe SDK client libraries in languages like TypeScript and Python. These SDKs act as subprocess wrappers, allowing developers to interact with CLI tools programmatically while benefiting from type checking, autocomplete, and validated arguments, effectively replacing fragile manual subprocess calls.

Some of the key features are:

• KDL Specification: Define CLI structures using the human-readable KDL document format.
• Shell Completions: Automatically generate tab completion scripts for multiple popular shells.
• Documentation Generation: Create manpages and markdown documentation that stay in sync with the CLI definition.
• Type-Safe SDKs: Generate robust client libraries for Python, TypeScript, and Rust to call CLIs programmatically.
• Framework Integrations: Extract usage specs from existing CLI frameworks such as Cobra, clap, Commander.js, and others.
• Multi-Shell Support: Run scripts in various environments with consistent flag parsing and validation.
• Shebang Integration: Use the usage shebang directly in scripts to enable powerful parsing and autocompletion features.
• Config & Env Integration: Define priority-based configurations backed by files, environment variables, or default values.

The tool is designed to be highly accessible through straightforward installation methods including Homebrew, Arch Linux, and Cargo. Once installed, developers can manage their projects by writing a .usage.kdl specification file. The Usage CLI can then be invoked to lint the specification or generate the required assets. For scripting workflows, developers can add a usage-specific shebang to their scripts, allowing the Usage CLI to handle argument parsing and completions dynamically at runtime without needing complex boilerplate code.

Some common use cases include:

• Streamlining Documentation: Keeping CLI help text, manpages, and readme files perfectly synchronized with the actual tool behavior.
• Generating Client Libraries: Providing typed programmatic access to internal platform CLIs for services written in different programming languages.
• Enhancing Developer Experience: Automatically providing cross-shell tab completion for internal scripts and tools.
• Migrating CLI Frameworks: Using integrations to bridge the gap between existing CLI frameworks and a standardized metadata format.
• Standardizing CLI Interfaces: Ensuring that complex command-line tools adhere to standard GNU-style options and behaviors.
• Improving CI/CD Workflows: Automating the generation of SDKs and documentation whenever a new version of a CLI is released.