ironclaw completion

Generate shell completion scripts for ironclaw

The ironclaw completion command generates shell completion scripts that enable tab completion for IronClaw commands, subcommands, and flags.

Usage

ironclaw completion --shell <shell>

--shell · string · required

Shell to generate completions for. Options: bash, zsh, fish, powershell, elvish

Supported Shells

Bash

Bourne Again Shell (Linux/macOS default)

Zsh

Z Shell (macOS Catalina+ default)

Fish

Friendly Interactive Shell

PowerShell

Windows PowerShell / PowerShell Core

Installation

Bash

1. Generate completion script

   ironclaw completion --shell bash > ~/.ironclaw-completion.bash
   
2. Source in your shell profile

   Add to ~/.bashrc or ~/.bash_profile:

   source ~/.ironclaw-completion.bash
   
3. Reload your shell

   source ~/.bashrc
   

Alternative: System-wide installation (requires sudo)

ironclaw completion --shell bash | sudo tee /etc/bash_completion.d/ironclaw

Zsh

1. Generate completion script

   ironclaw completion --shell zsh > ~/.zsh/completions/_ironclaw
   

   Create the directory if it doesn’t exist:

   mkdir -p ~/.zsh/completions
   
2. Add to fpath

   Add to ~/.zshrc (before compinit):

   fpath=(~/.zsh/completions $fpath)
   autoload -Uz compinit
   compinit
   
3. Reload your shell

   source ~/.zshrc
   

Alternative: System-wide installation

ironclaw completion --shell zsh | sudo tee /usr/local/share/zsh/site-functions/_ironclaw

Fish

1. Generate and install completion

   ironclaw completion --shell fish > ~/.config/fish/completions/ironclaw.fish
   
2. Reload completions

   fish_update_completions
   

PowerShell

1. Generate completion script

   ironclaw completion --shell powershell > $PROFILE\..\ironclaw-completion.ps1
   
2. Source in your PowerShell profile

   Add to your $PROFILE:

   . (Join-Path (Split-Path -Parent $PROFILE) "ironclaw-completion.ps1")
   
3. Reload PowerShell

   . $PROFILE
   

What Gets Completed

Shell completions provide tab completion for:

• Commands: ironclaw run, ironclaw onboard, ironclaw config, etc.
• Subcommands: config list, tool install, mcp add, etc.
• Flags: --help, --version, --cli-only, --no-db, etc.
• Options: --shell bash, --kind tool, --filter agent, etc.
• Paths: File paths for --config, --output, etc. (shell-dependent)

Examples

Test completions

After installation, try these examples:

# Type and press Tab
ironclaw <Tab>
# Shows: run, onboard, config, tool, mcp, memory, registry, pairing, service, doctor, status, completion

# Type and press Tab
ironclaw config <Tab>
# Shows: init, list, get, set, reset, path

# Type and press Tab
ironclaw tool install --<Tab>
# Shows: --force, --build, --help

Generate and preview

Generate completion script without installing:

# Preview for Bash
ironclaw completion --shell bash | less

# Save to file
ironclaw completion --shell zsh > ironclaw.zsh

Temporary completion

Enable completions for current session only (no file required):

# Bash
source <(ironclaw completion --shell bash)

# Zsh
source <(ironclaw completion --shell zsh)

# Fish
ironclaw completion --shell fish | source

Troubleshooting

Completions not working after installation

Common issues:

1. Shell not reloaded: Run source ~/.bashrc (or ~/.zshrc, etc.)
2. Wrong shell: Verify your current shell with echo $SHELL
3. Path not in fpath (Zsh): Ensure completion directory is in $fpath before compinit
4. Permissions: Ensure the completion file is readable: chmod +r ~/.ironclaw-completion.bash

Zsh completions not loading

For Zsh, ensure:

1. The completion file is in a directory listed in $fpath:
   echo $fpath
   
2. The file is named _ironclaw (underscore prefix)
3. compinit is called after adding to fpath:
   fpath=(~/.zsh/completions $fpath)
   autoload -Uz compinit
   compinit
   
4. Rebuild completion cache:
   rm -f ~/.zcompdump; compinit
   

PowerShell execution policy blocked script

If PowerShell blocks the script with an execution policy error:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then reload the profile:

. $PROFILE

Completions are outdated after IronClaw update

After updating IronClaw, regenerate completions to include new commands:

# Bash
ironclaw completion --shell bash > ~/.ironclaw-completion.bash
source ~/.bashrc

# Zsh
ironclaw completion --shell zsh > ~/.zsh/completions/_ironclaw
rm -f ~/.zcompdump; source ~/.zshrc

# Fish
ironclaw completion --shell fish > ~/.config/fish/completions/ironclaw.fish
fish_update_completions

Pre-generated Completions

IronClaw releases include pre-generated completion scripts in the installation directory:

~/.cargo/bin/ironclaw.bash   # Bash
~/.cargo/bin/ironclaw.zsh    # Zsh
~/.cargo/bin/ironclaw.fish   # Fish

You can source these directly instead of generating:

# Bash
echo 'source ~/.cargo/bin/ironclaw.bash' >> ~/.bashrc

# Zsh
echo 'source ~/.cargo/bin/ironclaw.zsh' >> ~/.zshrc

# Fish
ln -s ~/.cargo/bin/ironclaw.fish ~/.config/fish/completions/ironclaw.fish

Pre-generated completions are only available for installations via the official installer or Homebrew. Cargo installations do not include these files.

Related Commands

ironclaw --help

View all available commands and flags

Shell configuration

Installation and shell setup guide