jdx/usage v3.1.0

v3.1.0: Richer help output, stdin support, and zsh completion fixes

on GitHub

This release improves the CLI's --help output to render all the documentation-related fields that were previously only used in manpage and markdown generation, adds stdin support for piping specs into usage commands, and fixes a long-standing zsh completion annoyance with trailing spaces.

Highlights

• The --help / -h output is now much richer, rendering examples, before/after help text, version headers, author/license info, and deprecation markers -- fields that were previously only surfaced in generated manpages and markdown.
• You can now pipe a usage spec from another tool directly into usage via --file -, enabling workflows like jbang usage | usage generate markdown --file -.
• Zsh tab completions no longer insert unwanted trailing spaces after partial completions, fixing a bug reported nearly a year ago.

Added

• The built-in --help / -h rendering now includes before_help, after_help (and their _long variants), examples, a name+version header, author/license in the long help footer, and [deprecated: reason] markers on subcommands. Short help (-h) uses the base variants; long help (--help) prefers the _long variants with a fallback to the base ones. (#554 by @jdx, closes #549)

  For example, a spec like:

  before_help "Welcome to my CLI"
  after_help "See the project website for docs"
  example "mycli --verbose" header="Run with verbose output"

  will now render those sections in mycli --help output, not just in generated docs.

• All --file flags across generate, lint, and complete-word subcommands now accept - to read the usage spec from stdin. This enables piping specs from other tools without writing a temporary file. (#555 by @jdx, closes #546)

  jbang usage | usage generate markdown --file -
  cat myspec.kdl | usage lint --file -

  Not supported for exec / shell subcommands, which pass stdin through to the child process.

Fixed

• Zsh completions no longer append an unwanted trailing space after partial completions. Previously, completing node@ would produce node@ (with a space), and path completions like /opt/homebrew would not include a trailing slash. The generated zsh completion scripts now use _describe with -S '' instead of _arguments with command substitution, and directory completions include a trailing /. If you have existing generated zsh completions, regenerate them to pick up this fix. (#556 by @jdx, closes #67)

Full Changelog: v3.0.0...v3.1.0