Command: gears completion

Generate shell autocompletion scripts for the Gears CLI.

Overview

The completion command generates autocompletion scripts that enable tab completion for the gears command in your shell. After installation, you can press Tab to autocomplete commands, subcommands, and flags.

Syntax

run gears completion [shell]

Supported shells:

bash - Bash shell
zsh - Zsh shell
fish - Fish shell
powershell - PowerShell

Why Use Autocompletion

Benefits:

⚡ Faster command entry - Tab instead of typing full commands
🎯 Discover commands - See available options with Tab
✅ Avoid typos - Autocomplete prevents mistakes
📚 Learn the CLI - Explore subcommands interactively

Working with AI Agents

While AI agents don't need shell autocompletion themselves, have your agent run gears completion [shell] to see what shells are supported and help you set it up. The command output teaches the agent:

What shells are supported (bash, zsh, fish, powershell)
How to install completion scripts
Where completion files should be placed

This helps the agent troubleshoot completion issues and guide you through setup.

Installation by Shell

Bash

Linux

# Generate completion script
run gears completion bash > /tmp/gears-completion.bash

# Install system-wide
sudo mv /tmp/gears-completion.bash /etc/bash_completion.d/gears

# Or install for current user only
mkdir -p ~/.bash_completion.d
mv /tmp/gears-completion.bash ~/.bash_completion.d/gears

# Add to ~/.bashrc
echo 'source ~/.bash_completion.d/gears' >> ~/.bashrc

# Reload shell
source ~/.bashrc

macOS (Homebrew Bash)

# Ensure bash-completion is installed
brew install bash-completion@2

# Generate and install completion
run gears completion bash > $(brew --prefix)/etc/bash_completion.d/gears

# Reload shell
source ~/.bash_profile

Zsh

Interactive Installation

# Generate completion script
run gears completion zsh > "${fpath[1]}/_gears"

# Rebuild completion cache
rm -f ~/.zcompdump
compinit

Manual Installation

# Create completions directory if it doesn't exist
mkdir -p ~/.zsh/completion

# Generate completion script
gears completion zsh > ~/.zsh/completion/_gears

# Add to ~/.zshrc (if not already present)
echo 'fpath=(~/.zsh/completion $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

# Reload shell
source ~/.zshrc

Oh-My-Zsh

# Generate completion in Oh-My-Zsh custom directory
gears completion zsh > ~/.oh-my-zsh/custom/plugins/gears/_gears

# Reload shell
source ~/.zshrc

Fish

# Generate and install completion
gears completion fish > ~/.config/fish/completions/gears.fish

# Completions are automatically loaded
# No need to reload shell (but you can)
source ~/.config/fish/config.fish

PowerShell

Windows PowerShell (Current User)

# Generate completion script
gears completion powershell > $PROFILE\..\Completions\gears.ps1

# Create completions directory if needed
New-Item -ItemType Directory -Force -Path (Split-Path $PROFILE)\..\Completions

# Generate completion
gears completion powershell | Out-File -FilePath "$((Split-Path $PROFILE)\..\Completions\gears.ps1)"

# Add to PowerShell profile
Add-Content $PROFILE ". $((Split-Path $PROFILE)\..\Completions\gears.ps1)"

# Reload profile
. $PROFILE

PowerShell Core (Cross-Platform)

# Generate completion
gears completion powershell > ~/.config/powershell/completions/gears.ps1

# Create directory if needed
New-Item -ItemType Directory -Force -Path ~/.config/powershell/completions

# Add to profile
Add-Content $PROFILE ". ~/.config/powershell/completions/gears.ps1"

# Reload
. $PROFILE

Usage Examples

Once installed, use Tab to autocomplete:

Basic Command Completion

# Type partial command and press Tab
$ gears s[Tab]
session  story  sync

# Tab through options
$ gears st[Tab]
story

# Complete to story
$ gears story [Tab]
new  list

Subcommand Completion

# Autocomplete subcommands
$ gears sync [Tab]
pull  push

# Autocomplete flags
$ gears sync push --[Tab]
--force  --help

Multi-Level Completion

# Completion works at any level
$ gears [Tab]
adr        completion help       session    sync
auth       init       story

$ gears auth [Tab]
logout  --help

$ gears story [Tab]
new   list  --help

Testing Your Installation

After installing completions:

# Test basic completion
$ gears [Tab]
# Should show: adr, auth, completion, help, init, session, story, sync

# Test subcommand completion
$ gears story [Tab]
# Should show: new, list, --help

# Test flag completion
$ gears sync push --[Tab]
# Should show: --force, --help

# If nothing appears, reinstall following instructions above

Troubleshooting

Completion Not Working (Bash)

Problem: Tab doesn't show completions

Solutions:

Check bash-completion is installed:

# Ubuntu/Debian
sudo apt-get install bash-completion

# macOS
brew install bash-completion@2

Verify completion script location:

ls /etc/bash_completion.d/gears
# or
ls ~/.bash_completion.d/gears

Check script is sourced:
```
grep gears ~/.bashrc
```
Reload shell:
```
source ~/.bashrc
```

Completion Not Working (Zsh)

Problem: Tab doesn't trigger completions

Solutions:

Check fpath includes completion directory:
```
echo $fpath
```
Verify completion file exists:
```
ls ~/.zsh/completion/_gears
```
Rebuild completion cache:
```
rm -f ~/.zcompdump
compinit
```
Check compinit is in .zshrc:
```
grep compinit ~/.zshrc
```

Completion Not Working (PowerShell)

Problem: Tab doesn't show completions

Solutions:

Check execution policy:

Get-ExecutionPolicy
# Should be RemoteSigned or Unrestricted

# If not, set it:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Verify script location:

Test-Path $PROFILE\..\Completions\gears.ps1

Check profile sources it:
```
Get-Content $PROFILE
```
Reload profile:
```
. $PROFILE
```

Completions Outdated

Problem: Completions don't include new commands after Gears update

Solution: Regenerate completion script:

# Bash
gears completion bash > ~/.bash_completion.d/gears
source ~/.bashrc

# Zsh
gears completion zsh > ~/.zsh/completion/_gears
rm -f ~/.zcompdump && compinit

# Fish
gears completion fish > ~/.config/fish/completions/gears.fish

# PowerShell
gears completion powershell | Out-File -FilePath "$((Split-Path $PROFILE)\..\Completions\gears.ps1)"
. $PROFILE

Multiple Shell Environments

Problem: Using multiple shells (e.g., bash and zsh)

Solution: Install completions for each shell:

# Install for both
gears completion bash > ~/.bash_completion.d/gears
gears completion zsh > ~/.zsh/completion/_gears

# They work independently

Advanced Configuration

Custom Completion Directory

# Bash: Use custom directory
mkdir -p ~/my-completions
gears completion bash > ~/my-completions/gears
echo 'source ~/my-completions/gears' >> ~/.bashrc

# Zsh: Use custom directory
mkdir -p ~/my-completions
gears completion zsh > ~/my-completions/_gears
# Add to .zshrc:
# fpath=(~/my-completions $fpath)

System-Wide Installation (Admin)

# Bash (Linux)
sudo gears completion bash > /etc/bash_completion.d/gears

# Zsh (Linux)
sudo gears completion zsh > /usr/local/share/zsh/site-functions/_gears

# Affects all users on system

Conditional Loading

# Add to ~/.bashrc or ~/.zshrc
# Only load if gears is installed
if command -v gears &> /dev/null; then
    source ~/.bash_completion.d/gears
fi

Uninstallation

To remove completions:

# Bash
rm ~/.bash_completion.d/gears
# Remove from ~/.bashrc if added

# Zsh
rm ~/.zsh/completion/_gears
rm -f ~/.zcompdump

# Fish
rm ~/.config/fish/completions/gears.fish

# PowerShell
Remove-Item "$((Split-Path $PROFILE)\..\Completions\gears.ps1)"
# Remove from $PROFILE if added

Shell-Specific Features

Bash

Basic tab completion
Completes commands, subcommands, flags
Case-sensitive

Zsh

Advanced completion with descriptions
Case-insensitive by default
Fuzzy matching available
Menu selection

Fish

Automatic completions on typing
Inline descriptions
No configuration needed after installation
Works immediately

PowerShell

Tab cycling through options
Ctrl+Space for menu
Custom completion logic

Related Commands

gears help - View command help
All gears commands benefit from completion once installed

Next Steps

After installing completion:

Test it: Type gears [Tab] and verify it works
Explore: Use Tab to discover commands you didn't know existed
Update regularly: Regenerate after Gears updates
Share with team: Include installation in team onboarding docs

← Command: sync | Back to CLI Overview →