CLI Commands

Complete reference for all CCS commands and options.

Basic Usage

ccs [profile] [args...]

profile - Optional profile name (default: “default”)
args - Passed directly to Claude CLI

Profile Commands

Switch Profiles

ccs           # Use default Claude
ccs glm       # Use GLM profile
ccs glmt      # Use GLM with thinking mode
ccs kimi      # Use Kimi profile
ccs work      # Use work account
ccs gemini    # Use Gemini via OAuth

With Arguments

ccs glm --verbose
ccs /plan "add feature"
ccs glm /code "implement feature"

Account Management

Create Account Profile

ccs auth create <name>

Creates a new account profile and opens OAuth login.

List Profiles

ccs auth list

Shows all configured profiles with their status.

Set Default

ccs auth default <name>

Sets the default profile for ccs without arguments.

Reset Default

ccs auth reset-default

Restores the original CCS default profile.

Remove Profile

ccs auth remove <name> --force

Removes profile and deletes instance directory.

API Profile Management

Manage custom API key-based profiles:

# Create new API profile
ccs api create <name>

# List all API profiles
ccs api list

# Remove an API profile
ccs api remove <name>

OAuth Provider Commands

Basic Usage

ccs gemini "your prompt"
ccs codex "your prompt"
ccs agy "your prompt"
ccs qwen "your prompt"
ccs iflow "your prompt"

Authentication

ccs gemini --auth         # Auth only, no session
ccs gemini --auth --add   # Add another account

Multi-Account

ccs gemini --accounts     # List all accounts
ccs gemini --use <name>   # Switch to account

Model Configuration

ccs gemini --config       # Change model (interactive)
ccs agy --config          # Change model (interactive)

Multi-Account Management

# List all accounts for a provider
ccs gemini --accounts

# Switch to a specific account
ccs gemini --use <account-name>

# Add another account (requires --auth)
ccs gemini --auth --add

# Set account nickname
ccs gemini --nickname <name>

Logout

ccs gemini --logout       # Clear cached tokens
ccs codex --logout
ccs agy --logout

Headless Mode

ccs gemini --headless     # No browser, get URL for remote auth

Kiro-Specific Options

# Import token from Kiro IDE
ccs kiro --import

# Use normal browser (saves AWS login)
ccs kiro --no-incognito

CLIProxy Management

Manage the CLIProxyAPI binary:

# Show status and version
ccs cliproxy

# Show full help
ccs cliproxy --help

# Install specific version
ccs cliproxy --install <version>
# e.g., ccs cliproxy --install 6.5.53

# Update to latest version
ccs cliproxy --latest

Quota Management

Manage account quota and rotation:

# Show quota, tier, and pause status for all providers
ccs cliproxy status

# Show status for specific provider
ccs cliproxy status agy

# Pause an account from rotation
ccs cliproxy pause <provider> <account>
# e.g., ccs cliproxy pause agy user@gmail.com

# Resume a paused account
ccs cliproxy resume <provider> <account>
# e.g., ccs cliproxy resume agy user@gmail.com

CLIProxy Paths:

Path	Description
`~/.ccs/cliproxy/bin/cli-proxy-api`	Binary location
`~/.ccs/cliproxy/config.yaml`	Configuration
`~/.ccs/cliproxy/auth/`	OAuth tokens
`~/.ccs/cliproxy/sessions.json`	Session tracking
`~/.ccs/cliproxy/accounts.json`	Account registry

Default port: 8317

Remote Proxy Configuration

Connect to a remote CLIProxy server:

# Configure remote proxy via CLI flags
ccs <profile> --proxy-host <hostname> --proxy-port <port> --proxy-auth-token <token>

# Set proxy protocol (http/https)
ccs <profile> --proxy-protocol https

# Set health check timeout
ccs <profile> --proxy-timeout <ms>

# Allow self-signed certificates
ccs <profile> --allow-self-signed

# Force local proxy mode
ccs <profile> --local-proxy

# Fail if remote unreachable (no fallback)
ccs <profile> --remote-only

Migration Commands

Migrate to unified configuration format:

# Trigger manual migration
ccs migrate

# Show migration help
ccs migrate --help

Migrations run automatically on first launch after updates. Use ccs migrate to manually trigger or re-run migrations.

Utility Commands

Version

ccs --version

Shows CCS version and installation details:

CCS (Claude Code Switch) v5.0.0

Installation:
  Location: /home/user/.local/bin/ccs
  Config: ~/.ccs/config.json

Documentation: https://docs.ccs.kaitran.ca

Help

ccs --help

Shows comprehensive usage documentation.

Update

ccs update              # Standard update
ccs update --force      # Force reinstall
ccs update --beta       # Install beta channel
ccs update --force --beta  # Force beta install

Configuration Dashboard

ccs config
ccs config --port 3000  # Use specific port

Opens visual configuration dashboard at http://localhost:3000.

Dashboard Authentication CLI

Configure optional login protection for the dashboard:

# Interactive setup wizard
ccs config auth setup

# Show current auth configuration
ccs config auth show

# Disable authentication
ccs config auth disable

Setup Wizard Prompts:

Username (alphanumeric + underscore, 3-50 chars)
Password (min 8 chars, prompted twice)
Writes bcrypt hash to config.yaml

Environment variables CCS_DASHBOARD_AUTH_ENABLED, CCS_DASHBOARD_USERNAME, and CCS_DASHBOARD_PASSWORD_HASH override config.yaml values. A warning is shown during setup if ENV vars are detected.

Health Check

ccs doctor              # Run diagnostics
ccs doctor --fix        # Auto-fix issues
ccs doctor -f           # Short form

Checks configuration, symlinks, permissions, and provider status.

Sync Shared Data

ccs sync

Re-creates symlinks for shared commands, skills, and agents across profiles.

Cleanup

ccs cleanup

Removes orphaned resources, old CLIProxy logs, and temporary files. Helps reclaim disk space and resolve stale session issues.

Persist Command

Write profile environment variables to ~/.claude/settings.json for native Claude Code usage (IDE extensions, web-based Claude Code).

# Persist profile env vars to settings.json
ccs persist <profile>

# Skip confirmation prompts, auto-backup
ccs persist <profile> --yes
ccs persist <profile> -y

Supported Profiles:

API profiles (glm, glmt, kimi, custom API profiles)
CLIProxy profiles (gemini, codex, agy, qwen, kiro, ghcp)
Copilot profiles (requires copilot-api daemon running)

Account-based profiles are NOT supported by persist. Use CLAUDE_CONFIG_DIR environment variable instead.

Backup Management

Before modifying settings.json, CCS creates timestamped backups:

# List all available backups
ccs persist --list-backups

# Restore from latest backup
ccs persist --restore

# Restore from specific backup
ccs persist --restore 20260110_205324

Backup Details:

Location: ~/.claude/settings.json.backup.YYYYMMDD_HHMMSS
Maximum: 10 backups (oldest auto-deleted)
Permissions: 0o600 (owner read/write only)

Security Features

Symlink Rejection: Rejects symlinked settings.json or backup files (prevents malicious writes)
JSON Validation: Validates JSON integrity before restore
Masked Output: API keys and tokens are masked in console output
Backup Prompt: Default “yes” to backup before modification

Example Workflow

# Step 1: Persist GLM profile
ccs persist glm
# → Creates backup
# → Writes env vars to settings.json
# → Shows masked output

# Step 2: Later, restore original settings
ccs persist --restore
# → Restores from latest backup

Shell Completion

ccs --shell-completion
ccs -sc

Installs shell auto-completion scripts for bash/zsh/fish.

Token Management

ccs tokens

Manage authentication tokens for OAuth providers. View, refresh, or revoke tokens across all accounts.

Headless Delegation

Execute prompts without interactive session:

ccs -p "your prompt"
ccs --prompt "your prompt"
ccs glm -p "implement feature"

Headless mode is useful for CI/CD pipelines, automation scripts, and remote execution scenarios where interactive sessions aren’t available.

Copilot Commands

Copilot-specific subcommands for GitHub Copilot integration:

ccs copilot <subcommand>

Copilot commands require GitHub Copilot CLI access and appropriate subscription level (individual or business).

Environment Variables

Core Configuration

Variable	Description
`CCS_CONFIG`	Override config file path
`CCS_CLAUDE_PATH`	Override Claude CLI location
`NO_COLOR`	Disable colored output
`CCS_DEBUG`	Enable verbose debug logging
`CCS_DEBUG_LOG`	Enable debug logging (legacy)
`ANTHROPIC_AUTH_TOKEN`	API key for settings-based profiles
`ANTHROPIC_BASE_URL`	API base URL override
`ANTHROPIC_MODEL`	Model name override
`CLAUDE_CONFIG_DIR`	Claude config directory (used for instance isolation)

Remote Proxy Configuration

Variable	Description
`CCS_PROXY_HOST`	Remote proxy hostname
`CCS_PROXY_PORT`	Remote proxy port number
`CCS_PROXY_AUTH_TOKEN`	Remote proxy authentication token
`CCS_PROXY_PROTOCOL`	Proxy protocol (http/https)
`CCS_PROXY_TIMEOUT`	Remote proxy health check timeout (ms)
`CCS_PROXY_FALLBACK_ENABLED`	Enable fallback to local proxy if remote fails
`CCS_ALLOW_SELF_SIGNED`	Accept self-signed SSL certificates

Advanced Options

Variable	Description
`CCS_UNIFIED_CONFIG`	Enable unified config mode (config.yaml)
`CCS_MIGRATE`	Trigger automatic migration on startup
`CCS_SKIP_MIGRATION`	Skip automatic migration
`CCS_SKIP_PREFLIGHT`	Skip API key validation checks
`CCS_WEBSEARCH_SKIP`	Skip WebSearch hook integration
`CCS_PROFILE_TYPE`	Signal profile type to WebSearch hook

Configuration Paths

Path	Description
`~/.ccs/config.json`	Main configuration file
`~/.ccs/profiles.json`	Account profiles registry
`~/.ccs/instances/`	Isolated Claude instances
`~/.ccs/*.settings.json`	API profile settings
`~/.ccs/shared/`	Shared commands, skills, agents

Shared Data Structure

~/.ccs/shared/
├── commands/    # Custom commands (symlinked)
├── skills/      # Custom skills (symlinked)
└── agents/      # Custom agents (symlinked)

On Windows, copies are used instead of symlinks if symlinks are unavailable.

Exit Codes

Code	Meaning
0	Success
1	Error (config, profile, or execution)

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

​CLI Commands

​Basic Usage

​Profile Commands

​Switch Profiles

​With Arguments

​Account Management

​Create Account Profile

​List Profiles

​Set Default

​Reset Default

​Remove Profile

​API Profile Management

​OAuth Provider Commands

​Basic Usage

​Authentication

​Multi-Account

​Model Configuration

​Multi-Account Management

​Logout

​Headless Mode

​Kiro-Specific Options

​CLIProxy Management

​Quota Management

​Remote Proxy Configuration

​Migration Commands

​Utility Commands

​Version

​Help

​Update

​Configuration Dashboard

​Dashboard Authentication CLI

​Health Check

​Sync Shared Data

​Cleanup

​Persist Command

​Backup Management

​Security Features

​Example Workflow

​Shell Completion

​Token Management

​Headless Delegation

​Copilot Commands

​Environment Variables

​Core Configuration

​Remote Proxy Configuration

​Advanced Options

​Configuration Paths

​Shared Data Structure

​Exit Codes

CLI Commands

Basic Usage

Profile Commands

Switch Profiles

With Arguments

Account Management

Create Account Profile

List Profiles

Set Default

Reset Default

Remove Profile

API Profile Management

OAuth Provider Commands

Basic Usage

Authentication

Multi-Account

Model Configuration

Multi-Account Management

Logout

Headless Mode

Kiro-Specific Options

CLIProxy Management

Quota Management

Remote Proxy Configuration

Migration Commands

Utility Commands

Version

Help

Update

Configuration Dashboard

Dashboard Authentication CLI

Health Check

Sync Shared Data

Cleanup

Persist Command

Backup Management

Security Features

Example Workflow

Shell Completion

Token Management

Headless Delegation

Copilot Commands

Environment Variables

Core Configuration

Remote Proxy Configuration

Advanced Options

Configuration Paths

Shared Data Structure

Exit Codes