`complete` does not work for shell scripts

[german-molins]

While it does work when defined as part of usage of a mise task, it does not work as #USAGE complete of a standalone shell script with the usage shebang.

[jdx]

Thanks for the report! I tried to reproduce this but complete does work for me in a standalone shebang script, both at the root level and inside cmd blocks. For example, examples/example.sh already uses #USAGE complete "baz" run="..." and the complete_word_arg_completer test exercises it.

Could you share:

1. The exact script (or a minimal version) — in particular, are you writing #USAGE (no space) or # USAGE (with a space after #)? Today the extractor regex at lib/src/spec/mod.rs:309 only matches #USAGE / #[USAGE] / # [USAGE], so # USAGE will silently fall through and the whole script gets treated as raw KDL, which would fail loudly on the shebang line rather than only breaking complete. If that's what's happening, the fix is to relax the regex.
2. The shell you're using and how you're triggering completion (typing <Tab> in a real shell vs. invoking usage complete-word directly).
3. Whether the script is on $PATH and the completion script was generated via usage generate completion <shell> <bin> --file <script>.

A minimal repro would help a lot here.

This comment was generated by Claude Code.

[german-molins]

Thank you for you answer!

Usage header for which I'm trying to get autocompletion by typing <Tab>:

#!/usr/bin/env -S usage bash
#USAGE arg "<input_pdf>" help="PDF file"
#USAGE complete "input_pdf" run="ls *.pdf"

The script is on $PATH, but even running it directly I'm not getting the completions. I didn't generate any completions for it (I couldn't figure out how to generate a .kdl from it either), I was just expecting that I don't need to generate any if it's a script with the usage shebang. But maybe this is my main misunderstanding and I misread the docs.

[german-molins]

Ok, everything clear now. You can close it unless you want to keep it because of the docs.

[jdx]

You were right that this is a gap — opened #620 to fix it.

The PR adds usage g completion-init <shell> (bash/zsh/fish), a one-time init you source from your shell rc that wires up <Tab> for any command on $PATH whose first line is a usage shebang. No per-script usage g completion step needed.

# bash:  ~/.bashrc
source <(usage g completion-init bash)

# zsh:   ~/.zshrc
source <(usage g completion-init zsh)

# fish:  ~/.config/fish/conf.d/usage.fish
usage g completion-init fish | source

Once that's installed, your original example should just work:

#!/usr/bin/env -S usage bash
#USAGE arg "<input_pdf>" help="PDF file"
#USAGE complete "input_pdf" run="ls *.pdf"

Drop the script anywhere on $PATH and tab-complete — no other setup. I'll close this once #620 lands.

This comment was generated by Claude Code.

[jdx]

PR #620 is merged. The completion-init flow now ships for bash, zsh, and fish. Once you've updated, your original example should just work after adding the one-liner to your shell rc:

# bash:  ~/.bashrc
source <(usage g completion-init bash)

# zsh:   ~/.zshrc
source <(usage g completion-init zsh)

# fish:  ~/.config/fish/conf.d/usage.fish
usage g completion-init fish | source

Reload your shell and tab-complete on any usage shebang script on \$PATH. Closing this issue — please reopen if completion still doesn't work for you after the install step.

This comment was generated by Claude Code.