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 kimi      # Use Kimi OAuth (CLIProxy)
ccs km        # Use Kimi API key (Kimi for Coding direct)
ccs work      # Use work account
ccs gemini    # Use Gemini via OAuth

ccs glmt is deprecated and kept only for compatibility with existing legacy scripts or configs. Use ccs glm for Z.AI API profiles and ccs km for reasoning-first Kimi API profiles.

With Arguments

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

Account Management

Create Account Profile

ccs auth create <name> [--bare] [--force] [--share-context] [--context-group <name>] [--deeper-continuity]

Creates a new account profile and opens OAuth login.

Bare Profiles

ccs auth create sandbox --bare

The --bare flag creates a clean profile without shared symlinks (commands, skills, agents, settings.json). Bare profiles are useful for sandboxed or testing environments where you want a minimal Claude instance with no inherited configuration. Bare vs non-bare behavior:

Aspect	Non-bare (default)	Bare (`--bare`)
Shared commands/skills/agents	Symlinked from `~/.ccs/shared/`	Not linked
MCP server sync	Synced from global `~/.claude.json`	Skipped
`ccs sync`	Updates MCP servers	Skipped
OAuth credentials	Isolated per instance	Isolated per instance

Once created with --bare, the flag persists across profile updates and ccs sync runs.

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:

Basic Operations

# Create new API profile
ccs api create [name] [--preset <preset>] [--base-url <url>] [--target claude|droid]

# List all API profiles
ccs api list

# Remove an API profile
ccs api remove <name>

Profile Lifecycle (Discover, Copy, Export, Import)

Available since v7.52.0

# Discover orphaned .settings.json files
ccs api discover

# Discover and register orphaned profiles
ccs api discover --register

# Copy existing profile to new name
ccs api copy <source> <target>

# Export profile to portable JSON file
ccs api export <name> --out <file.json>

# Export with API key included
ccs api export <name> --out <file.json> --include-secrets

# Import profile from JSON file
ccs api import <file.json>

# Import to specific profile name
ccs api import <file.json> --name <name>

Using API Profiles

# Run with API profile
ccs glm "your prompt"
ccs km "analyze this"
ccs llamacpp "local task"
ccs anthropic "direct API"

# Configure specific profile
ccs config
# Navigate to API Profiles tab

OAuth Provider Commands

Basic Usage

ccs gemini "your prompt"
ccs codex "your prompt"
ccs agy "your prompt"
ccs kimi "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

# Auth method selection
ccs kiro --kiro-aws-login       # AWS device code (default)
ccs kiro --kiro-aws-authcode    # AWS authorization code
ccs kiro --kiro-google-login    # Google OAuth

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

Codex Reasoning Effort

# Override reasoning effort
ccs codex --effort medium       # Standard reasoning
ccs codex --effort high         # Deep reasoning
ccs codex --effort xhigh        # Maximum, capped by model support
ccs codex --thinking xhigh      # Alias for --effort

gpt-5-codex and gpt-5-codex-mini cap at high. gpt-5.2-codex, gpt-5.3-codex, gpt-5.3-codex-spark, and gpt-5.4 support xhigh.

Cursor Integration

Beta feature since v7.42.0

ccs cursor auth               # Auto-detect from Cursor SQLite
ccs cursor auth --manual      # Manual token import
ccs cursor status              # Show integration status
ccs cursor models              # List available models
ccs cursor start               # Start daemon
ccs cursor stop                # Stop daemon
ccs cursor enable              # Enable in config
ccs cursor disable             # Disable in config

Droid Multi-Target Adapter

Route profiles to alternative CLI targets:

# Explicit target flag
ccs glm --target droid

# Built-in ccsd shorthand (busybox argv0 pattern)
ccsd glm "your prompt"      # Equivalent to: ccs glm --target droid
ccsd agy "your prompt"      # Any profile works
ccsd codex "prompt"

# Custom aliases via env var
export CCS_DROID_ALIASES=mydroid
mydroid glm "your prompt"

Setup ccsd:

ln -s $(which ccs) /usr/local/bin/ccsd

See Droid Adapter for full documentation.

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

Lifecycle Commands

# Start CLIProxy
ccs cliproxy start

# Restart CLIProxy
ccs cliproxy restart

# Stop CLIProxy
ccs cliproxy stop

# Show status (PID, port, sessions)
ccs cliproxy status

Variant Management

# Create single-provider variant
ccs cliproxy create [name]

# Create composite variant (mix providers per tier)
ccs cliproxy create --composite

# Edit existing variant
ccs cliproxy edit [name]

# Remove variant
ccs cliproxy remove <name>

# List all variants
ccs cliproxy list

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
ccs cliproxy status claude   # Claude OAuth quota
ccs cliproxy status ghcp     # GitHub Copilot quota

# Show quota summary across all supported providers
ccs cliproxy quota

ccs cliproxy quota displays quota sections for all supported providers: agy, codex, gemini, claude, and ghcp.

# 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

Model Catalog Sync

Available since v7.39.0

Sync remote model catalogs from CLIProxyAPI with static fallback catalogs:

# View current catalog cache status
ccs cliproxy catalog

# Force refresh from remote
ccs cliproxy catalog refresh

# Reset to static catalog (clear cache)
ccs cliproxy catalog reset

Syncable Providers: agy, gemini, codex, claude Cache Details:

Location: ~/.ccs/model-catalog-cache.json
TTL: 24 hours
Merge strategy: Remote overrides static fields, static-only fields preserved

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) v7.39.0

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

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
ccs config --host 0.0.0.0   # Reachable from another device
ccs config --host 127.0.0.1 # Force local-only binding

Opens the visual configuration dashboard in your browser using the effective bind/port. By default CCS uses the runtime’s system-default bind. When the effective bind is reachable beyond loopback, CCS prints network URLs plus an auth reminder.

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.

If you expose the dashboard beyond localhost, protect it first with ccs config auth setup.

Claude IDE Extension Setup

Generate setup for the Anthropic Claude extension in VS Code-compatible hosts:

# Preferred shared-settings path
ccs persist glm
ccs persist work
ccs persist default

# IDE-local settings.json snippets
ccs env glm --format claude-extension --ide vscode
ccs env work --format claude-extension --ide cursor
ccs env default --format claude-extension --ide windsurf

Host-specific output:

vscode, cursor → claudeCode.environmentVariables plus claudeCode.disableLoginPrompt
windsurf → claude-code.environmentVariables

Dashboard parity:

ccs config → Claude Extension
Copy the shared ~/.claude/settings.json payload or an IDE-local JSON snippet

Thinking Configuration

Configure extended thinking/reasoning budget settings:

# Show current thinking config
ccs config thinking

# Set mode
ccs config thinking --mode auto           # Tier-based defaults
ccs config thinking --mode off            # Disable thinking
ccs config thinking --mode manual         # Use override value

# Persistent override
ccs config thinking --override high
ccs config thinking --override 24576
ccs config thinking --clear-override

# Per-tier defaults
ccs config thinking --tier opus high
ccs config thinking --tier sonnet medium
ccs config thinking --tier haiku low

# Per-provider overrides
ccs config thinking --provider-override gemini opus xhigh
ccs config thinking --provider-override agy sonnet high
ccs config thinking --clear-provider-override gemini
ccs config thinking --clear-provider-override gemini opus

See Extended Thinking for full documentation.

Image Analysis Configuration

Configure automatic image and PDF analysis via CLIProxy vision models:

# Show current image analysis configuration
ccs config image-analysis

# Enable image analysis
ccs config image-analysis --enable

# Disable image analysis
ccs config image-analysis --disable

Default Behavior:

Image analysis is enabled by default for all CLIProxy providers
Automatically analyzes images and PDFs before Claude processes them
Prevents context overflow with visual descriptions instead of raw image data
Supported formats: JPEG, PNG, GIF, WebP, HEIC, BMP, TIFF, PDF

Use Cases:

Screenshots and architecture diagrams
PDF documents and forms
Technical images and diagrams
Any visual content Claude needs to analyze

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. Also syncs MCP servers from global ~/.claude.json to all non-bare profile instances.

MCP Server Sync

During ccs sync (and on every profile launch), CCS copies the mcpServers key from global ~/.claude.json into each instance’s .claude.json. Merge behavior:

Global MCP servers are used as the base
Instance-specific MCP server overrides are preserved (instance wins on conflict)
Only the mcpServers key is copied — OAuth sessions, caches, and other keys are not touched

Exclusions:

Bare profiles (--bare) are skipped entirely
Instances without a directory are skipped

MCP sync only copies server configuration. OAuth sessions and cached credentials in ~/.claude.json are never shared with instances.

Cleanup

ccs cleanup

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

Persist Command

Write the resolved Claude setup to ~/.claude/settings.json for native Claude Code usage (IDE extensions, web-based Claude Code).

# Persist a profile's resolved Claude setup to settings.json
ccs persist <profile>

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

Supported Profiles:

API profiles (glm, km, custom API profiles)
CLIProxy profiles (gemini, codex, agy, qwen, kiro, kimi, ghcp)
Copilot profiles (requires copilot-api daemon running)
Account profiles created with ccs auth create
default profile

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 resolved setup to settings.json
# → Shows masked output

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

Environment Export

Export environment variables for third-party tool integration (OpenCode, Cursor, Continue, etc.).

ccs env <profile> [--format openai|anthropic|raw|claude-extension] [--shell auto|bash|zsh|fish|powershell] [--ide vscode|cursor|windsurf]

Formats:

Format	Variables	Use Case
`openai`	`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `LOCAL_ENDPOINT`, `OPENAI_MODEL`	OpenCode, Cursor, Continue
`anthropic`	`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`	Claude-compatible tools
`claude-extension`	Host-specific `settings.json` snippet	Anthropic Claude extension in VS Code, Cursor, Windsurf
`raw`	All effective env vars	Debugging, custom scripts, inspecting `CLAUDE_CONFIG_DIR`

Shell Syntax:

Shell	Flag	Auto-detected
Bash/Zsh	`bash` or `zsh`	From `$SHELL` (default)
Fish	`fish`	From `$SHELL` containing `fish`
PowerShell	`powershell`	From `$SHELL` containing `pwsh` or Windows

Supported Profile Types:

Profile Type	Example	Supported
CLIProxy (OAuth)	`gemini`, `codex`, `agy`, `qwen`, `kiro`, `kimi`, `ghcp`	Yes
Settings (API)	`glm`, `km`, custom	Yes
Copilot	`copilot`	Yes
Account/default	`work`, `personal`, `default`	Yes (`claude-extension`; `raw` for `CLAUDE_CONFIG_DIR`)

Examples:

# OpenAI-compatible vars for OpenCode/Cursor
eval $(ccs env gemini --format openai)

# Anthropic vars for Claude-compatible tools
ccs env codex --format anthropic

# Fish shell syntax
eval (ccs env agy --format openai --shell fish)

# PowerShell
ccs env gemini --format openai --shell powershell | Invoke-Expression

# Settings-based profiles (glm, km)
eval $(ccs env glm --format raw)

The --format flag defaults to anthropic. The --shell flag defaults to auto (detects from $SHELL environment variable). The zsh shell option maps to bash syntax since they are compatible.

--ide <host> applies to --format claude-extension and accepts vscode, cursor, or windsurf.

For account and default profiles, --format claude-extension is the primary path. --format raw can expose CLAUDE_CONFIG_DIR, while openai and anthropic only produce transport vars for settings, CLIProxy, and Copilot profiles.

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).

Copilot Usage Quota

ccs copilot usage

Shows current GitHub Copilot quota consumption:

GitHub Copilot Usage
  Premium interactions: 42 / 300
  Chat:                 128 / 500
  Completions:          2341 / unlimited
  Plan:                 individual
  Quota resets:         2026-03-01

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

Thinking

Variable	Description
`CCS_THINKING`	Per-session thinking override. Accepts: `minimal`, `low`, `medium`, `high`, `xhigh`, `auto`, `off`, `none`, `disabled`, `0`, or integer budget (0-100000)

Droid / Multi-Target

Variable	Description
`CCS_DROID_ALIASES`	Comma-separated binary names mapping to droid target
`CCS_DROID_PATH`	Explicit path to droid binary

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.yaml`	Main configuration file
`~/.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

CCS uses standardized exit codes following Unix conventions:

Code	Meaning	Description
0	SUCCESS	Successful execution
1	GENERAL_ERROR	General/unspecified error
2	CONFIG_ERROR	Configuration file errors (missing, invalid, corrupt)
3	NETWORK_ERROR	Network-related errors (connection, timeout, DNS)
4	AUTH_ERROR	Authentication/authorization errors (invalid token, expired, forbidden)
5	BINARY_ERROR	Binary/executable errors (missing Claude CLI, corrupted binary)
6	PROVIDER_ERROR	Provider-specific errors (API errors, rate limits, service unavailable)
7	PROFILE_ERROR	Profile not found or invalid
8	PROXY_ERROR	Proxy-related errors (startup failure, port conflict)
9	MIGRATION_ERROR	Migration errors (failed to migrate config)
130	USER_ABORT	User aborted operation (Ctrl+C, SIGINT)

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

​CLI Commands

​Basic Usage

​Profile Commands

​Switch Profiles

​With Arguments

​Account Management

​Create Account Profile

​Bare Profiles

​List Profiles

​Set Default

​Reset Default

​Remove Profile

​API Profile Management

​Basic Operations

​Profile Lifecycle (Discover, Copy, Export, Import)

​Using API Profiles

​OAuth Provider Commands

​Basic Usage

​Authentication

​Multi-Account

​Model Configuration

​Multi-Account Management

​Logout

​Headless Mode

​Kiro-Specific Options

​Codex Reasoning Effort

​Cursor Integration

​Droid Multi-Target Adapter

​CLIProxy Management

​Lifecycle Commands

​Variant Management

​Quota Management

​Model Catalog Sync

​Remote Proxy Configuration

​Migration Commands

​Utility Commands

​Version

​Help

​Update

​Configuration Dashboard

​Dashboard Authentication CLI

​Claude IDE Extension Setup

​Thinking Configuration

​Image Analysis Configuration

​Health Check

​Sync Shared Data

​MCP Server Sync

​Cleanup

​Persist Command

​Backup Management

​Security Features

​Example Workflow

​Environment Export

​Shell Completion

​Token Management

​Headless Delegation

​Copilot Commands

​Copilot Usage Quota

​Environment Variables

​Core Configuration

​Remote Proxy Configuration

​Thinking

​Droid / Multi-Target

​Advanced Options

​Configuration Paths

​Shared Data Structure

​Exit Codes

CLI Commands

Basic Usage

Profile Commands

Switch Profiles

With Arguments

Account Management

Create Account Profile

Bare Profiles

List Profiles

Set Default

Reset Default

Remove Profile

API Profile Management

Basic Operations

Profile Lifecycle (Discover, Copy, Export, Import)

Using API Profiles

OAuth Provider Commands

Basic Usage

Authentication

Multi-Account

Model Configuration

Multi-Account Management

Logout

Headless Mode

Kiro-Specific Options

Codex Reasoning Effort

Cursor Integration

Droid Multi-Target Adapter

CLIProxy Management

Lifecycle Commands

Variant Management

Quota Management

Model Catalog Sync

Remote Proxy Configuration

Migration Commands

Utility Commands

Version

Help

Update

Configuration Dashboard

Dashboard Authentication CLI

Claude IDE Extension Setup

Thinking Configuration

Image Analysis Configuration

Health Check

Sync Shared Data

MCP Server Sync

Cleanup

Persist Command

Backup Management

Security Features

Example Workflow

Environment Export

Shell Completion

Token Management

Headless Delegation

Copilot Commands

Copilot Usage Quota

Environment Variables

Core Configuration

Remote Proxy Configuration

Thinking

Droid / Multi-Target

Advanced Options

Configuration Paths

Shared Data Structure

Exit Codes