ccs/scripts/completion/README.md

Shell Completion for CCS

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

The completion scripts are thin adapters over the hidden ccs __complete backend so all supported shells stay aligned with the same command graph.

Supported Shells: Bash, Zsh, Fish, PowerShell

Features

• Complete profile names (both settings-based and account-based)
• Complete root commands, help topics, provider shortcuts, and command flags
• Complete ccs auth and ccs api lifecycle 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

Help and verification:

ccs help completion
ccs --shell-completion --force

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      api       cliproxy  config    doctor    docker    help

$ ccs help <TAB>
profiles  providers  completion  targets

Context Completion

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

$ ccs api <TAB>
create    discover  copy      export  import  remove

Backend Contract

$ ccs __complete --shell bash --current do
doctor
docker

Shell adapters now call the shared CCS completion backend instead of maintaining their own copy of the command graph. That means:

• top-level commands, help topics, and provider shortcuts come from CCS itself
• dynamic profiles and CLIProxy variants resolve through the real config loaders
• bash, zsh, fish, and PowerShell stay aligned with the same completion logic

Troubleshooting

Bash

1. Check if completion is loaded:

   complete -p ccs
   

2. Verify the backend directly:

   ccs __complete --shell bash --current "" -- help
   

Zsh

1. Verify completion system is enabled:

   autoload -Uz compinit && compinit
   

2. Rebuild the cache if needed:

   rm ~/.zcompdump && compinit
   

3. Verify the backend directly:

   ccs __complete --shell zsh --current "" -- help
   

PowerShell

1. Check that the profile exists:

   Test-Path $PROFILE
   

2. Verify the backend directly:

   ccs __complete --shell powershell --current "" -- help
   

Fish

1. Verify completion file location:

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

2. Test completion manually:

   complete -C'ccs '
   

3. Verify the backend directly:

   ccs __complete --shell fish --current "" -- help
   

Technical Details

• Bash uses complete -F
• Zsh uses a custom _ccs completion function
• Fish uses complete -a with backend command substitution
• PowerShell uses Register-ArgumentCompleter
• All four shells now delegate suggestion logic to ccs __complete

Contributing

When adding or changing command surfaces:

1. Update the shared TypeScript command/completion catalog
2. Run bun run validate
3. Smoke-check at least one installed shell adapter plus the backend directly

See Also

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