ccs/scripts/completion

Shell Completion for CCS

Tab completion for CCS commands, subcommands, profiles, and flags.

Supported Shells: Bash, Zsh, Fish, PowerShell

Features

• Complete profile names (both settings-based and account-based)
• Complete ccs auth subcommands (create, list, show, remove, default)
• Complete flags (--help, --version, --json, --verbose, --yes)
• Complete profile names for auth subcommands
• Context-aware: suggests relevant options based on current command

Quick Install (Recommended)

ccs --shell-completion

This will:

• Auto-detect your shell
• Copy completion files to ~/.ccs/completions/
• Configure your shell profile with proper comment markers
• Show instructions to activate

Manual shell selection:

ccs --shell-completion --bash        # Force bash
ccs --shell-completion --zsh         # Force zsh
ccs --shell-completion --fish        # Force fish
ccs --shell-completion --powershell  # Force PowerShell

Manual Installation

Completion files are installed to ~/.ccs/completions/ during npm install.

Bash

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

# CCS shell completion
source ~/.ccs/completions/ccs.bash

Then reload:

source ~/.bashrc

Zsh

1. Create completion directory:

   mkdir -p ~/.zsh/completion
   

2. Copy completion file:

   cp ~/.ccs/completions/ccs.zsh ~/.zsh/completion/_ccs
   

3. Add to ~/.zshrc:

   # CCS shell completion
   fpath=(~/.zsh/completion $fpath)
   autoload -Uz compinit && compinit
   

4. Reload:

   source ~/.zshrc
   

PowerShell

Add to your PowerShell profile ($PROFILE):

# CCS shell completion
. "$HOME\.ccs\completions\ccs.ps1"

Then reload:

. $PROFILE

Fish

User installation (recommended)

Fish automatically loads completions from ~/.config/fish/completions/:

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

# Copy completion script
cp scripts/completion/ccs.fish ~/.config/fish/completions/

That's it! Fish will automatically load the completion on demand. No need to source or reload.

System-wide installation (requires sudo)

sudo cp scripts/completion/ccs.fish /usr/share/fish/vendor_completions.d/

Usage Examples

Basic Completion

$ ccs <TAB>
auth      doctor    glm       glmt      kimi      work      personal  --help    --version

$ ccs auth <TAB>
create    list      show      remove    default   --help

Profile Completion

$ ccs auth show <TAB>
work      personal  team      --json

$ ccs auth remove <TAB>
work      personal  team      --yes     -y

Flag Completion

$ ccs auth list <TAB>
--verbose --json

$ ccs auth show work <TAB>
--json

Completion Behavior

Top-level (after ccs)

• Built-in commands: auth, doctor
• Flags: --help, --version, -h, -v
• Settings-based profiles: from ~/.ccs/config.json
• Account-based profiles: from ~/.ccs/profiles.json

After ccs auth

• Subcommands: create, list, show, remove, default
• Flags: --help, -h

After ccs auth <subcommand>

• create: No completion (user enters new profile name)
  • Flags: --force
• list: No profile completion
  • Flags: --verbose, --json
• show: Account profiles only
  • Flags: --json
• remove: Account profiles only
  • Flags: --yes, -y
• default: Account profiles only

After ccs <profile>

• No completion (Claude CLI arguments are free-form)

Troubleshooting

Bash: Completion not working

1. Check if bash-completion is installed:

   # macOS
   brew install bash-completion
   
   # Ubuntu/Debian
   sudo apt install bash-completion
   

2. Verify jq is installed (required for profile completion):

   command -v jq
   

3. Check if completion is loaded:

   complete -p ccs
   

   Should output:

   complete -F _ccs_completion ccs
   

Zsh: Completion not working

1. Verify completion system is enabled in ~/.zshrc:

   autoload -Uz compinit && compinit
   

2. Check if completion is loaded:

   which _ccs
   

3. Rebuild completion cache:

   rm ~/.zcompdump && compinit
   

PowerShell: Completion not working

1. Check PowerShell version (5.1+ required):

   $PSVersionTable.PSVersion
   

2. Verify profile is loaded:

   Test-Path $PROFILE
   

3. Check if completion is registered:

   (Get-ArgumentCompleter).CommandName | Select-String ccs
   

Fish: Completion not working

1. Check Fish version (3.0+ required):

   fish --version
   

2. Verify completion file is in the right location:

   ls ~/.config/fish/completions/ccs.fish
   

3. Verify jq is installed (required for profile completion):

   which jq
   

4. Test completion manually:

   complete -C'ccs '
   

5. If needed, rebuild completions:

   fish_update_completions
   

Technical Details

Bash Implementation

• Uses complete -F for programmable completion
• Compatible with bash 3.2+ (macOS default)
• Reads profiles dynamically using jq
• Context-aware based on COMP_CWORD and COMP_WORDS

Zsh Implementation

• Uses _arguments and _describe for rich completion
• Compatible with zsh 5.0+
• Supports completion descriptions
• Context-aware using $state and $words

PowerShell Implementation

• Uses Register-ArgumentCompleter
• Compatible with PowerShell 5.1+
• Reads profiles dynamically using ConvertFrom-Json
• Provides CompletionResult objects

Fish Implementation

• Uses declarative complete command
• Compatible with Fish 3.0+
• Automatic loading from ~/.config/fish/completions/
• Helper functions for dynamic profile loading
• Context-aware using __fish_seen_subcommand_from
• No manual sourcing required

Dependencies

• jq: Required for reading profiles from JSON files
  • Install: brew install jq (macOS) or apt install jq (Ubuntu)
  • Already required by CCS core functionality

Contributing

When adding new commands or flags:

1. Update all four completion scripts (bash, zsh, fish, PowerShell)
2. Test on each shell
3. Update this README with new completion examples
4. Maintain cross-shell parity

See Also

• CCS Documentation
• Bash Programmable Completion
• Zsh Completion System
• Fish Completion Tutorial
• PowerShell Argument Completers