xingzhouandAyaan Zaidi
2cb55600a0
Fixes #149788 ## What Problem This Solves Bash suggests `--json` for `openclaw cron show -- --j`, although that word is positional. ## Why This Change Was Made The Bash scanner tracks the option terminator using registered option metadata. Required operands can still be `--`; optional operands leave following options alone. Both paths share final candidate generation. This state has one writer: the Bash callback. The two production files grow by 33 lines to carry required-operand facts and track the terminator. ## User Impact Options and their values stop appearing after `--`. Root, nested and aliased command names remain available. ## Evidence Generated with `pnpm openclaw completion --shell bash` and sourced in clean Bash 3.2 and 5.3: main returns `--json`; the fix returns zero candidates. `openclaw -- g` still returns `gateway`. Registered-command tests: 16 failures on main; all 57 pass with the fix. Five related test files add 96 passes; 109 native Fish/PowerShell checks skip because those shells are unavailable. Types, lint, formatting, export and docs checks pass. ## Compatibility Accepted arguments and other shell generators do not change. Required values, short groups, quoting, word breaks and cursor controls remain covered. ## Consumers Bash uses the new private metadata; other generators ignore it. ## Invalidation Refresh cached scripts with `openclaw completion --shell bash --write-state`, then reload the shell. Updates already refresh the cache. ## Tests One registered command generates the shared Bash fixture; existing scanner and cache-write assertions remain intact. Co-authored-by: Ayaan Zaidi <hi@obviy.us>
5.5 KiB
summary, read_when, title
| summary | read_when | title | ||
|---|---|---|---|---|
| CLI reference for `openclaw completion` (generate/install shell completion scripts) |
|
Completion |
openclaw completion
Generate shell completion scripts, cache them under OpenClaw state, and optionally install them into your shell profile.
Usage
openclaw completion # print the detected shell's script
openclaw completion --shell fish # print fish script
openclaw completion --write-state # cache scripts for all shells
openclaw completion --write-state --install # cache, then install in one step
openclaw completion --shell bash --write-state
Options
-s, --shell <shell>: shell target, one ofzsh,bash,powershell, orfish. Detected from$SHELL, otherwise PowerShell on Windows and zsh elsewhere.-i, --install: install completion by adding a source line for the cached script to your shell profile--write-state: write completion script(s) to$OPENCLAW_STATE_DIR/completions(default~/.openclaw/completions) without printing to stdout. With--shellit writes only that shell, otherwise all four.-y, --yes: skip install confirmation prompts (non-interactive)
Install flow
--install points your profile at the cached script, so the cache must exist first. If the cache is missing, the command fails and tells you to run openclaw completion --write-state. Combine --write-state --install to do both in one step. Without --shell, the command preserves a recognized $SHELL. When $SHELL is missing or unrecognized, it defaults to PowerShell on Windows and zsh elsewhere.
The install writes a small # OpenClaw Completion block into your shell profile and replaces any older slow source <(openclaw completion ...) lines with the cached source line:
| Shell | Profile |
|---|---|
| bash | ~/.bashrc (falls back to ~/.bash_profile when ~/.bashrc is missing) |
| fish | ~/.config/fish/config.fish |
| powershell | ~/.config/powershell/Microsoft.PowerShell_profile.ps1 (on Windows: Documents/PowerShell/Microsoft.PowerShell_profile.ps1, or Documents/WindowsPowerShell/... for Windows PowerShell) |
| zsh | $ZDOTDIR/.zshrc when ZDOTDIR is defined; otherwise ~/.zshrc (an empty ZDOTDIR resolves to /.zshrc) |
Profile changes are staged beside the destination and atomically replace it only after a complete durable write. A failed install leaves an existing profile unchanged.
Installed source lines preserve literal cache paths, including spaces, quotes, dollar signs, and backslashes. Reinstalling replaces OpenClaw's previous source line after the state directory changes.
A user-managed portable hook for the same cached script (for example [[ -f "${HOME}/.openclaw/completions/openclaw.bash" ]] && source "${HOME}/.openclaw/completions/openclaw.bash", as a dotfile manager would write) is recognized as completion being configured. Doctor and completion --install leave such managed lines byte-for-byte untouched instead of appending a duplicate literal-path block.
Permission failures
If Doctor or onboarding cannot update your shell profile, completion remains optional and setup continues. When a cache is available, the warning includes a command to load that cache in your current matching shell session. Run the complete command as printed. This does not install completion for future shell sessions.
For persistent installation, resolve the reported permission or read-only error
before retrying openclaw completion --install. The failure location may be a
staging directory or a symlink target, not the profile itself. Atomic replacement
also needs write access to the destination directory. The installer uses the
profile selected in the table above. It has no profile-file destination option.
Notes
- Without
--installor--write-state, the command prints the script to stdout. - Completion generation eagerly loads the full command tree, including plugin CLI commands, so nested subcommands are included.
- If invalid configuration prevents plugin discovery, generation warns and still includes core commands. Repair the configuration and regenerate to include plugin commands.
- Bash completion supports both
--flag valueand--flag=value, including named profiles before nested commands and single-quoted, double-quoted, or backslash-escaped value prefixes. - After an option terminator (
--), Bash completes command names but does not suggest options or option values. - PowerShell completes commands and option values at the cursor, including when later arguments are already present.
openclaw updaterefreshes the completion cache automatically after a successful update.openclaw doctorcan repair missing or stale completion setups.