jdx/usage v5.1.0

v5.1.0: Embed specs from strings, cleaner include metadata

on GitHub

A small feature release: embedders get a string-based script parser, included specs stop clobbering their parent's inferred metadata, and the test suite finally runs cleanly on Windows.

Added

• Parse embedded USAGE comments from a string (#782 by @jdx). The new Spec::parse_script_str lets embedders turn a script body into a Spec without writing to a temp file or hand-deserializing KDL:

  let spec = Spec::parse_script_str(r#"
  #!/bin/bash
  #USAGE bin "mycli"
  #USAGE flag "--foo" help="a flag"
  "#)?;

  Because there's no source path, bin/name are not inferred from a filename and relative include paths are rejected with relative includes require a source file; absolute includes still work. The file-based parse_script now shares the same internal path, so behavior stays consistent.

Fixed

• Included specs no longer overwrite parent metadata (#786 by @jdx). parse_file derives a missing bin (and then name) from the filename — but include was going through the same path, so an empty included fragment would take on its own filename and overwrite the parent spec, producing a spurious missing-cmd-help. Filename-based inference is now limited to the top-level spec; explicit metadata in includes still merges as before. The unreachable missing-name lint (which fired for stdin but never for files) was also removed so file and stdin linting behave the same way. Closes #784 and #785.

Changed

• Corrected USAGE comment marker documentation (#782). The docs previously described # USAGE: and // USAGE:; the real supported markers are #USAGE, //USAGE, ::USAGE, and their [USAGE] variants.
• Bumped rmcp to v3 (#780 by @renovate). Tracks the MCP 2026-07-28 protocol revision.

Tests

• Windows test suite is fully green (#771 by @JamBalaya56562). Reworks the shell skip guards to probe the actual precondition instead of a proxy (WSL's bash.exe cheerfully answers --version and then fails everything else), routes fixture invocations through USAGE_SHELL_<SHELL>, normalizes paths handed to shell script bodies and $PATH, and removes the #![cfg(unix)] gate on shell_override.rs — which held back the very tests for the Windows-facing USAGE_SHELL_<SHELL> feature added in v5.0.0. Result on a windows-latest runner: 538 passed, 0 skipped. No library or CLI source is touched.

Full Changelog: v5.0.0...v5.1.0

💚 Sponsor usage

usage is maintained by @jdx, an open source developer for entire.io, the title sponsor of the jdx.dev open source tools including mise, aube, hk, and more. Work on usage is funded by sponsorships.

If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider sponsoring at jdx.dev. Every sponsorship helps the project stay independent and moving.