Unifying and simplifying shell completion across jdx tools

[lhs-12]

Hi @jdx, I use a lot of the tools you've built, and they have one thing in common: they all use usage for shell completion.

For example, here is what the docs recommend for fish completion with aube and pitchfork:

# aube: `https://aube.sh/installation.html#shell-completions`
aube completion fish --install

# pitchfork: `https://pitchfork.jdx.dev/installation.html#shell-completion`
pitchfork completion fish > ~/.config/fish/completions/pitchfork.fish

Two tools built on the same foundation recommend different installation methods: one uses --install, the other prints the shim and asks you to redirect it. I understand aube generates three completion files (aube, aubr, and aubx), but both approaches still end up writing a long shim into a file, and that shim changes between versions (for example, usage 6.x to 7.x). Most users are not going to remember to maintain a file that long.

usage-rs provides some building blocks, but each tool still writes its own completion subcommand. Could this be standardized upstream?

The docs for mise, aube, and pitchfork also seem incomplete about which shells are supported. Some supported shells are not listed. That could be fixed in the docs.

Also, I had AI review the docs, and it reported that a lot of the wording is out of date. For example, the aube docs say to install usage, but it is not actually needed. The pitchfork docs say the scripts are self-contained, but they are shims, which makes it sound like the file contains the full completion table.

---

This is what I use now. It is different from what the docs recommend, but it works well enough for me, and it is simple and always uses the installed version:

# ~/.config/fish/completions/aube.fish
aube completion fish | source

# ~/.config/fish/completions/pitchfork.fish
pitchfork completion fish | source

---

What I would like:

1. Simplicity: the completion files generated by these tools should not be one long shim.
2. Version following: the contents of the completion file should be generated dynamically, instead of a long block that can go stale when the tool is upgraded.
3. Consistent installation: aube uses --install, pitchfork prints the shim. For example, is there a way to provide a shared completion subcommand in usage-rs that downstream tools can wire up directly?
4. Multi-shell support: the same rules should apply to different shells.

---

Also, AI reported a possible bug in mise's completion shim. I have not verified it myself, so you may want to look. Here is the original AI output, followed by the reproduction steps it added:

mise's shim intercepts the tool's __complete_word__. In fish, if mise shims come before the tool in PATH, sourcing aube's completion and then running complete -C "aube ins" returns mise's install and installs, not aube's. Calling .mise-bins/aube __complete_word__ directly works. The same happens with pitchfork. So the two lines in my fish config are actually wrong right now, even though completion appears to work.

Reproduction:
  source ~/.config/fish/completions/aube.fish
  complete -C "aube ins"
  # returns mise's install and installs

  ~/.local/share/mise/shims/aube __complete_word__ --shell fish --line "aube ins"
  # returns mise's install and installs

  ~/.local/share/mise/installs/aube/latest/.mise-bins/aube __complete_word__ --shell fish --line "aube ins"
  # returns aube's install and install-clean

  ~/.local/share/mise/shims/pitchfork __complete_word__ --shell fish --line "pitchfork st"
  # returns \x01files

  ~/.local/share/mise/installs/pitchfork/latest/.mise-bins/pitchfork __complete_word__ --shell fish --line "pitchfork st"
  # returns start/stat/status/stop

Environment:
  aube 2.9.0
  pitchfork 2.33.1
  mise 2026.11.2
  usage 7.2.0

[github-actions[bot]]

Implemented in #1624: feat(lib): add a shared completion subcommand to usage-rs

[lhs-12]

@jdx Thanks for the quick response. I've seen the related PRs in usage, mise, pitchfork, and aube, and I hope more tools (fnox, for example) follow the same approach.

---

One more documentation note. Some shells or distributions may already ship a completion loader, so users do not need to generate the file themselves. For example, fish 4.9.3 runs mise completion fish | source when completing mise, so mise completion fish --install is redundant there. Other shells or older fish versions may not have that loader. The mise docs could add a small note telling users they can skip the manual install when their shell or distribution already provides a completion loader.

---

One more thing: I just had AI collect and summarize the implementations in these PRs, and it noticed a small inconsistency in the output channel. Details below:

The shared Completion added in #1624 has a small inconsistency in where it writes:

• The existing aube/mise --install: install messages go to stderr, stdout stays empty.
• usage g completion --install: same, stderr, and the code comment explicitly says stdout should stay empty.
• The new shared Completion: run takes a writer, and the docs example passes std::io::stdout(). With that example, --install writes installed /path and already up to date: /path to stdout.

Completion is ultimately the implementation of the CLI command. run does not force stdout; out is chosen by the caller. The docs example chooses stdout, so a downstream tool that copies it ends up with CLI behavior that differs from the existing stderr paths. The usage g completion code and comment are still there, so both behaviors now exist. pitchfork #1105 also collects Completion::run output into a buffer and writes it to stdout, so it inherits this.

A few possible directions:

• If the new command should standardize on stdout, say so in the docs and align the existing stderr paths and comments.
• If install messages should stay on stderr, adjust the new API or docs. Right now run has only one writer, and the script and install message share it. The docs example could branch on --install and pass stderr for installs; or the API could return the result and let the caller decide how to print it.

#1627 only handles the effect labels and related docs; it does not touch the output channel.

---

AI-assisted — Tool: Pi; model: deepseek-flash

[jdx]

Thanks for the detailed write-up. I checked the stdout/stderr point and you're right: Completion::run sends the script and the --install report to one writer, so the docs example printed installed /path on stdout, unlike usage generate completion --install.

#1629 adds Completion::run_split(bin, out, report). Pass stdout and stderr, and ex completion fish prints only the script while --install reports on stderr and leaves stdout empty. run is unchanged because changing it would break a published API; making it behave this way is recorded in V8.md for the next major release. The docs example now uses run_split.

I haven't acted on the other two points yet: the note about shells that already load completions, and the mise shim intercepting __complete_word__. The shim concern isn't in this repo and I haven't reproduced it.

AI-assisted — Tool: Claude Code; model: anthropic/claude-sonnet-5-5; version: unavailable.