mirror of
https://github.com/openclaw/openclaw.git
synced 2026-09-28 14:12:28 +08:00
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>
75 lines
5.5 KiB
Markdown
75 lines
5.5 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw completion` (generate/install shell completion scripts)"
|
|
read_when:
|
|
- You want shell completions for zsh/bash/fish/PowerShell
|
|
- You need to cache completion scripts under OpenClaw state
|
|
title: "Completion"
|
|
---
|
|
|
|
# `openclaw completion`
|
|
|
|
Generate shell completion scripts, cache them under OpenClaw state, and optionally install them into your shell profile.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
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 of `zsh`, `bash`, `powershell`, or `fish`. 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 `--shell` it 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 `--install` or `--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 value` and `--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 update` refreshes the completion cache automatically after a successful update. `openclaw doctor` can repair missing or stale completion setups.
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|