Skip to content

SHELL-COMPLETION.md

Latest commit

 

History

History
342 lines (232 loc) · 8.09 KB

SHELL-COMPLETION.md

File metadata and controls

342 lines (232 loc) · 8.09 KB
Raw

Shell Completion for autospec

autospec provides built-in shell completion support for bash, zsh, fish, and powershell using Cobra's completion system.

Features

  • Automatic command completion: Tab-complete all commands (full, prep, specify, plan, tasks, implement, etc.)
  • Flag completion: Complete command flags (e.g., --max-retries, --debug, --specs-dir)
  • Stays in sync: Automatically updates as commands change
  • Multiple shells: Works with bash, zsh, fish, and powershell
  • One-command installation: Use autospec completion install to automatically configure your shell

Quick Start (Recommended)

The easiest way to set up shell completions is using the install command:

# Auto-detect your shell and install completions
autospec completion install

# Or specify a shell explicitly
autospec completion install bash
autospec completion install zsh
autospec completion install fish
autospec completion install powershell

This command:

  1. Auto-detects your shell from the $SHELL environment variable
  2. Creates a backup of your shell configuration file (e.g., ~/.bashrc.autospec-backup-YYYYMMDD-HHMMSS)
  3. Appends the completion configuration to your rc file
  4. Provides instructions for activating the completions

Options

# Show manual installation instructions without modifying files
autospec completion install --manual

# Show manual instructions for a specific shell
autospec completion install bash --manual

How It Works

  • Bash/Zsh/PowerShell: Appends a sourcing block to your rc file that loads completions dynamically
  • Fish: Writes a completion file directly to ~/.config/fish/completions/autospec.fish

The installed completions use eval/source style, meaning they automatically stay up-to-date when you upgrade autospec - no need to regenerate completion files!

Backup Files

Before modifying any rc file, a timestamped backup is created:

  • Format: ~/.bashrc.autospec-backup-20231215-143022
  • Backups are retained permanently for easy recovery

Idempotency

The install command is idempotent - running it multiple times won't add duplicate entries. If completions are already installed, the command detects the existing configuration and skips installation.

Manual Setup

If you prefer manual control or the automatic installation doesn't work for your setup, follow the shell-specific instructions below.

Zsh Setup (Manual)

1. Generate Completion File

# Create completions directory
mkdir -p ~/.zsh_completions

# Generate completion file
autospec completion zsh > ~/.zsh_completions/_autospec

2. Configure Your Shell

Add these lines to your ~/.zshrc (before any existing compinit call):

# Add custom completions directory to fpath
fpath=(~/.zsh_completions $fpath)

# Initialize completion system (if not already present)
autoload -U compinit
compinit

Important: The fpath line must appear before compinit. If you already have compinit in your .zshrc, add the fpath line above it.

3. Reload Your Shell

exec zsh

4. Test It

autospec <tab>

You should see all available subcommands with descriptions. If you have fzf installed, you'll get fuzzy filtering!

Bash Setup (Manual)

1. Generate Completion File

# System-wide (requires root)
autospec completion bash | sudo tee /etc/bash_completion.d/autospec > /dev/null

# User-specific
mkdir -p ~/.bash_completions
autospec completion bash > ~/.bash_completions/autospec

2. Configure Your Shell

Add to your ~/.bashrc:

# Load autospec completion
if [ -f ~/.bash_completions/autospec ]; then
    source ~/.bash_completions/autospec
fi

3. Reload Your Shell

source ~/.bashrc

Fish Setup (Manual)

1. Generate Completion File

autospec completion fish > ~/.config/fish/completions/autospec.fish

2. Reload Completions

source ~/.config/fish/config.fish
# or just start a new shell

PowerShell Setup (Manual)

1. Generate Completion Script

autospec completion powershell | Out-String | Invoke-Expression

2. Add to Profile (Persistent)

# Add to your PowerShell profile
autospec completion powershell >> $PROFILE

Verification

After setup, test completion works:

# Type and press TAB
autospec <TAB>

# Should show:
# full       -- Run complete workflow: specify → plan → tasks → implement
# prep       -- Prepare for implementation: specify → plan → tasks
# specify    -- Generate feature specification
# plan       -- Generate implementation plan
# tasks      -- Generate task list
# implement  -- Execute implementation
# doctor     -- Check dependencies
# status     -- Show current spec status
# config     -- Manage configuration
# init       -- Initialize configuration
# version    -- Show version information
# completion -- Generate completion script
# help       -- Help about any command

Advanced Features

Flag Completion

Complete flags for any command:

autospec prep --<TAB>

# Shows:
# --max-retries    -- Maximum number of retry attempts
# --dry-run        -- Show what would be executed without running
# --skip-preflight -- Skip pre-flight dependency checks
# --debug          -- Enable debug logging
# --specs-dir      -- Specs directory path
# --config         -- Config file path

Subcommand Completion

autospec config <TAB>

# Shows:
# show   -- Display current configuration

Context-Aware Completion

Some shells provide intelligent completion based on context. For example, in zsh with fuzzy completion:

autospec imp<TAB>
# Fuzzy matches to "implement"

Troubleshooting

Completion Not Working

Check if completion file exists:

# Zsh
ls -la ~/.zsh_completions/_autospec

# Bash
ls -la ~/.bash_completions/autospec

# Fish
ls -la ~/.config/fish/completions/autospec.fish

Verify fpath (zsh only):

echo $fpath | grep zsh_completions

Should show ~/.zsh_completions in the path.

Rebuild completion cache (zsh only):

rm -f ~/.zcompdump*
exec zsh

Check compinit is called (zsh only):

grep -n compinit ~/.zshrc

Make sure fpath modification appears before compinit.

Completion Shows Old Commands

Regenerate the completion file:

# Zsh
autospec completion zsh > ~/.zsh_completions/_autospec

# Reload
exec zsh

Permission Issues

Make sure completion files are readable:

chmod 644 ~/.zsh_completions/_autospec

Updating Completions

When you update autospec, regenerate completion files:

# Zsh
autospec completion zsh > ~/.zsh_completions/_autospec
exec zsh

# Bash
autospec completion bash > ~/.bash_completions/autospec
source ~/.bashrc

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

How It Works

autospec uses Cobra's built-in completion system, which automatically generates completion scripts from the command structure.

When you run autospec completion <shell>, Cobra:

  1. Analyzes all registered commands and flags
  2. Generates shell-specific completion code
  3. Outputs a completion script for your shell

This means:

  • Completions are always accurate and up-to-date
  • No manual maintenance required
  • New commands automatically get completion support
  • Supports multiple shells with zero extra work

Platform-Specific Notes

macOS

On macOS, bash is often outdated (v3.x). For best results:

  1. Install modern bash via Homebrew: brew install bash
  2. Or use zsh (default shell since macOS Catalina)

Windows

Use WSL (Windows Subsystem for Linux) and follow the Linux/bash instructions.

Linux

Most Linux distributions use bash or zsh by default. Follow the respective setup instructions above.

See Also