This is a maintenance release with no user-facing changes. The only modification is an internal CI/CD improvement that extracts the AI-powered release-note enhancement step into a separate GitHub Actions job, making it independently re-runnable if it fails due to transient errors.

There are no changes to the library, CLI, shell completions, spec format, or documentation.

Full Changelog: v2.17.4...v2.18.0

2.17.4 - 2026-02-18

🐛 Bug Fixes

• (publish) retry draft release creation until tag is indexed by @jdx in #510

This release adds two significant features: shell completion support for nushell users and a new Go package for generating usage specs from Cobra CLI definitions.

Highlights

Nushell Completions

usage now generates shell completions for nushell, joining bash, zsh, fish, and PowerShell as a supported shell. The implementation uses nushell's module system and @complete syntax to provide dynamic completions that call back to usage complete-word at runtime—the same approach used by the other shells.

Thanks to @abusch for contributing this! #485

Cobra (Go) Integration

A new Go package at integrations/cobra/ converts Cobra command trees into usage specs. If you have a Go CLI built with Cobra, you can now generate shell completions, markdown docs, and man pages from your existing command definitions without writing a spec by hand.

The package provides a straightforward API:

• Generate(cmd) — returns a KDL spec string
• GenerateJSON(cmd) — returns a JSON spec
• GenerateToFile(cmd, path) / GenerateJSONToFile(cmd, path) — write specs to disk

It maps Cobra commands, flags (persistent and local), positional args, aliases, ValidArgs choices, hidden/deprecated markers, and more. See the Cobra integration docs for setup details. #498

Integrations Framework Tracker

The new integrations directory documents the roadmap for framework support across languages. Clap (Rust) and Cobra (Go) are implemented; Commander.js, Click, Typer, and others are planned. #497 #499

New Contributors

• @abusch made their first contribution in #485

A small bug fix release. The main change fixes an issue where KDL spec authors couldn't use common properties like help, long_help, required, var, and hide as child nodes inside arg { ... } blocks — they would cause parse errors. These now work correctly, matching the existing behavior for flags.

Bug Fixes

• Arg child node parsing: arg definitions now support help, long_help, help_long, help_md, required, var, var_min, var_max, hide, and double_dash as child nodes inside {} blocks. Previously only choices, env, and default were supported, causing parse errors for other properties. (#489)

This patch release fixes an important parsing bug for variadic arguments and includes documentation improvements.

Bug Fixes

• Variadic argument parsing: Fixed handling of variadic ellipsis inside brackets like [args...]. Previously, this syntax could cause parsing issues - now it works correctly whether you use <args>..., [args]..., or [args...]. (#481)

Documentation

• Added documentation for the bash array pattern when working with variadic arguments, making it clearer how to handle multiple values in your scripts. (#480)

For full documentation, visit usage.jdx.dev.

This release brings full Windows support to usage, including pre-built Windows binaries and PowerShell completion fixes.

Highlights

Windows Binaries and Completion Support

usage now provides native Windows binaries and fixes PowerShell completion support (#472). Windows users can now:

• Download pre-built binaries for Windows
• Use shell completions with PowerShell
• Generate man pages, markdown docs, and completions on Windows just like on Unix platforms

If you've been waiting to use usage on Windows, this release removes that barrier. Check out the documentation to get started with defining your CLI specs and generating completions for PowerShell.

This patch release fixes an important bug in argument parsing when using default_subcommand with nested subcommands.

Bug Fixes

• Fixed nested subcommand parsing after default_subcommand switch - Previously, when a spec used default_subcommand and the command had nested subcommands, parsing could fail or produce incorrect results. This is now handled correctly. (#469)

For more information, see the usage documentation.

This release introduces a new Parser builder API that gives you fine-grained control over how environment variables are resolved during argument parsing. Instead of relying on the default behavior of reading from std::env, you can now provide your own environment variable lookup function.

Highlights

Parser Builder for Custom Env Var Handling

The new Parser builder pattern (#464) allows you to customize how environment variables are resolved when parsing CLI arguments. This is particularly useful for:

• Testing: Mock environment variables without modifying the actual environment
• Sandboxed execution: Control which env vars are visible to the parser
• Custom variable sources: Pull values from configuration files or other sources

let args = Parser::new(&spec, &argv)
    .with_env(|key| custom_env_lookup(key))
    .parse()?;

Internal Improvements

• Added cargo-semver-checks to CI to automatically detect breaking API changes (#463) by @jdx
• Improved test assertions using fish output format for cleaner test output (#461) by @ilyagr

For full documentation, visit usage.jdx.dev.

This release brings expanded lint checks to help catch spec issues earlier, along with an important fix for shell completions when flag or argument names contain special characters. Documentation has also been significantly improved with rustdoc coverage across the public API.

Highlights

More Lint Checks (#446)

The usage lint command now catches additional spec issues, helping you identify problems before they cause runtime errors. Run usage lint on your specs to validate them against the expanded ruleset.

Completion Prefix Matching Fix (#460)

Shell completions now correctly match against unescaped names, fixing issues where completions wouldn't work properly for flags or arguments containing characters that needed escaping. Thanks to @ilyagr for this contribution!

Builder API Additions (#444)

Missing builder methods have been added to the library, making it easier to construct specs programmatically in Rust code.

Bug Fixes

• Better error messages - Error output now includes more context to help diagnose issues (#449)
• Fig completion handling - Replaced panicking unwrap() calls with proper error handling in fig.rs (#454)
• PowerShell test reliability - Tests now skip gracefully when pwsh isn't installed (#457)

Documentation

The public API now has comprehensive rustdoc coverage (#450, #453, #455), making it easier to use usage as a library. Check out the updated docs at usage.jdx.dev.

New Contributors

• @ilyagr made their first contribution in #460

usage v2.13.1 Release Notes

This patch release fixes a compatibility issue with PowerShell completion generation. Users generating shell completions for PowerShell should upgrade to ensure proper functionality.

Bug Fixes

PowerShell Completion Fix

Fixed incorrect casing in the PowerShell enum variant that could cause issues when generating shell completions. PowerShell is case-sensitive in certain contexts, and the variant name now uses the correct PowerShell casing instead of Powershell. This ensures completions are generated and recognized correctly by PowerShell. (#438) - @jdx

For full documentation, visit https://usage.jdx.dev/