# 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) ```bash 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:** ```bash 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`: ```bash # CCS shell completion source ~/.ccs/completions/ccs.bash ``` Then reload: ```bash source ~/.bashrc ``` ### Zsh 1. Create completion directory: ```zsh mkdir -p ~/.zsh/completion ``` 2. Copy completion file: ```zsh cp ~/.ccs/completions/ccs.zsh ~/.zsh/completion/_ccs ``` 3. Add to `~/.zshrc`: ```zsh # CCS shell completion fpath=(~/.zsh/completion $fpath) autoload -Uz compinit && compinit ``` 4. Reload: ```zsh source ~/.zshrc ``` ### PowerShell Add to your PowerShell profile (`$PROFILE`): ```powershell # CCS shell completion . "$HOME\.ccs\completions\ccs.ps1" ``` Then reload: ```powershell . $PROFILE ``` ### Fish **User installation (recommended)** Fish automatically loads completions from `~/.config/fish/completions/`: ```fish # 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)** ```fish sudo cp scripts/completion/ccs.fish /usr/share/fish/vendor_completions.d/ ``` ## Usage Examples ### Basic Completion ```bash $ ccs auth doctor glm glmt kimi work personal --help --version $ ccs auth create list show remove default --help ``` ### Profile Completion ```bash $ ccs auth show work personal team --json $ ccs auth remove work personal team --yes -y ``` ### Flag Completion ```bash $ ccs auth list --verbose --json $ ccs auth show work --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 ` - **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 ` - No completion (Claude CLI arguments are free-form) ## Troubleshooting ### Bash: Completion not working 1. Check if bash-completion is installed: ```bash # macOS brew install bash-completion # Ubuntu/Debian sudo apt install bash-completion ``` 2. Verify jq is installed (required for profile completion): ```bash command -v jq ``` 3. Check if completion is loaded: ```bash complete -p ccs ``` Should output: ``` complete -F _ccs_completion ccs ``` ### Zsh: Completion not working 1. Verify completion system is enabled in `~/.zshrc`: ```zsh autoload -Uz compinit && compinit ``` 2. Check if completion is loaded: ```zsh which _ccs ``` 3. Rebuild completion cache: ```zsh rm ~/.zcompdump && compinit ``` ### PowerShell: Completion not working 1. Check PowerShell version (5.1+ required): ```powershell $PSVersionTable.PSVersion ``` 2. Verify profile is loaded: ```powershell Test-Path $PROFILE ``` 3. Check if completion is registered: ```powershell (Get-ArgumentCompleter).CommandName | Select-String ccs ``` ### Fish: Completion not working 1. Check Fish version (3.0+ required): ```fish fish --version ``` 2. Verify completion file is in the right location: ```fish ls ~/.config/fish/completions/ccs.fish ``` 3. Verify jq is installed (required for profile completion): ```fish which jq ``` 4. Test completion manually: ```fish complete -C'ccs ' ``` 5. If needed, rebuild completions: ```fish 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](https://github.com/kaitranntt/ccs) - [Bash Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html) - [Zsh Completion System](http://zsh.sourceforge.net/Doc/Release/Completion-System.html) - [Fish Completion Tutorial](https://fishshell.com/docs/current/completions.html) - [PowerShell Argument Completers](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/register-argumentcompleter)