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 codex     # Use Codex 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. For two isolated Claude accounts, create both profiles and run the one you want explicitly:

ccs auth create work
ccs auth create personal
ccs work "review code"
ccs personal "write tests"

Account credentials and tokens stay isolated per profile. Non-bare profiles share settings.json and user CLAUDE.md from ~/.claude/; history sharing is separate and only happens when accounts use shared mode and the same context group.

Bare Profiles

ccs auth create sandbox --bare

The --bare flag creates a clean profile without shared symlinks (commands, skills, agents, settings.json, or CLAUDE.md). 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
Shared settings/instructions	Linked 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.

Show Profile

ccs auth show <name>
ccs auth show <name> --json

Shows credential isolation, account context mode, settings.json sync state, local history summary, and whether plain ccs currently resumes from the same lane.

Set Default

ccs auth default <name>

Sets the default profile for plain ccs launches. Back up the current native lane first if you might need old ~/.claude/projects history:

ccs auth backup default
ccs auth default work

Changing the default aligns future plain ccs runs with that account profile. It does not import old native history into the selected profile.

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.

Shared Resources

ccs auth resources <profile>
ccs auth resources <profile> --mode shared|profile-local
ccs auth resources <profile> --json

Inspect or change whether a profile shares plugins, settings, CLAUDE.md, commands, skills, and agents from ~/.claude/, or keeps them profile-local.

--mode shared links shared resources into the profile instance (default for most profiles).
--mode profile-local (equivalent to ccs auth create --bare) isolates the profile from ~/.claude/ so the instance carries its own resource set.
Without --mode, prints the current mode and effective behavior.
--json emits machine-readable output for scripts.

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|codex]

# 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

Built-in CLIProxy provider shortcuts now include: agy · claude · codex · xai · gemini · qwen · iflow · kimi · kiro · cursor · gitlab · codebuddy · kilo · qoder Deprecated compatibility shortcut: ghcp grok is an alias for xai; both commands share accounts, settings, model catalog, and routing. Qwen account linking is currently unavailable in the bundled CLIProxy runtime. Use an API-key Qwen profile such as Alibaba Coding Plan instead.

Basic Usage

ccs codex "your prompt"
ccs xai "your prompt" # ccs grok is equivalent
ccs kimi "your prompt"
ccs iflow "your prompt"
ccs cursor "your prompt"
ccs gitlab "your prompt"
ccs qoder "your prompt"
ccs <oauth-provider> "your prompt"

Authentication

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

Multi-Account

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

Model Configuration

ccs codex --config       # Change model (interactive)
ccs kimi --config        # Change model (interactive)
ccs xai --config         # Change model (interactive)

GitLab Duo Auth Variants

# Browser OAuth
ccs gitlab --auth

# PAT login instead of browser OAuth
ccs gitlab --auth --gitlab-token-login

# Self-hosted GitLab
ccs gitlab --auth --gitlab-url https://gitlab.example.com

Multi-Account Management

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

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

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

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

Logout

ccs codex --logout       # Clear cached tokens
ccs kiro --logout

Headless Mode

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

Kiro-Specific Options

# Import token from Kiro IDE
ccs kiro --import

# Auth method selection
ccs kiro --auth --kiro-auth-method aws
ccs kiro --auth --kiro-auth-method aws-authcode --paste-callback
ccs kiro --auth --kiro-auth-method google
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start

# 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.4-mini caps at high. gpt-5.2, gpt-5.3-codex, gpt-5.3-codex-spark, gpt-5.4, and gpt-5.5 support xhigh. For Codex GPT models that expose the fast service tier, append -fast to the model ID. Combine it with effort suffixes when you want both controls:

gpt-5.4-fast
gpt-5.4-high-fast
gpt-5.4-xhigh-fast
gpt-5.5-high-fast

CCS sends the canonical upstream model, for example gpt-5.4, with reasoning.effort and service_tier: "priority" instead of forwarding the suffixed string as a raw upstream model name.

Cursor Provider And Legacy Bridge

The current ccs cursor shortcut is a CLIProxy provider. The older local Cursor daemon workflow still exists only under ccs legacy cursor.

# Current provider path
ccs cursor --auth
ccs cursor --accounts
ccs cursor --config
ccs cursor "your prompt"

# Deprecated compatibility path
ccs legacy cursor auth
ccs legacy cursor status
ccs legacy cursor start
ccs legacy cursor probe

Older ccs cursor auth/status/start/... subcommands are still shimmed for a migration window, but they forward to the legacy bridge with a deprecation warning.

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 codex "your prompt"    # OAuth-backed profile on Droid
ccsd km "prompt"            # API profile on Droid

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

Codex Runtime Target

Available since v7.62.0

Route profiles to the native Codex CLI:

# Built-in aliases
ccs-codex "your prompt"
ccsx codex "implement auth flow"

# Codex-on-Codex power shortcut (native Codex + CLIProxy Codex pool)
ccsxp "your prompt"

# Explicit target flag
ccs codex --target codex "your prompt"

# Custom aliases
export CCS_TARGET_ALIASES='codex=mycodex'
# Legacy: export CCS_CODEX_ALIASES=mycodex

Setup aliases:

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

Most Codex target credentials are delivered via transient -c overrides and CCS_CODEX_API_KEY env var. ccsxp also repairs the native Codex [model_providers.cliproxy] entry when needed and injects the managed token into that provider’s env_key; no API key is written to disk. See Codex 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

Codex variants can pin both effort and fast mode through the model value:

ccs cliproxy create codex-fast --provider codex --model gpt-5.4-high-fast

Dashboard parity:

ccs config -> CLIProxy
Create or edit a Codex variant
Pick gpt-5.4-fast, gpt-5.4-high-fast, or gpt-5.4-xhigh-fast in the model selector

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     # Deprecated GitHub Copilot compatibility quota

# Show quota summary across all supported providers
ccs cliproxy quota

ccs cliproxy quota displays quota sections for supported providers such as agy, codex, gemini, and claude. ghcp may appear for existing deprecated Copilot compatibility setups. When automatic quota management is enabled, CCS checks the full active account pool before local CLIProxy startup. Known-exhausted accounts are temporarily paused out of rotation when another healthy account exists, then automatically resume after the cooldown window.

# 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

Routing Strategy

Inspect and change the proxy-wide routing strategy explicitly:

# Show current strategy and source
ccs cliproxy routing

# Explain the tradeoff
ccs cliproxy routing explain

# Change strategy
ccs cliproxy routing set fill-first
ccs cliproxy routing set round-robin

Available strategies:

round-robin - spread requests across matching healthy accounts
fill-first - drain one healthy account before moving to backups

CCS keeps round-robin as the default until you explicitly change it.

Pool Routing

Turn several Claude accounts into a pool that auto-continues when one account hits its limit. See Account Pools for the full guide.

# Show pool routing status
ccs cliproxy pool

# Enable pool routing (fill-first + session affinity + cooling on + retry cap)
ccs cliproxy pool --enable

# Disable pool routing and restore a safe non-pool config
ccs cliproxy pool --disable

Use ccs cliproxy pool --disable to leave a pool. Do not hand-edit routing back to plain round-robin with no affinity on a multi-account fleet; that state re-processes your whole conversation on most turns. See Leaving a pool.

Account Drain Order

Control the order accounts are drained in within a provider:

# Show the effective drain order
ccs cliproxy accounts order <provider>

# Set a manual order (comma-separated account IDs)
ccs cliproxy accounts order <provider> --set a@x.com,b@y.com

# Derive order from tier metadata (ultra > pro > free); agy and gemini only
ccs cliproxy accounts order <provider> --by-tier

# Revert to stable file order
ccs cliproxy accounts order <provider> --reset

Tier-based ordering (--by-tier) is available for agy and gemini. Claude accounts have unknown tier; use --set for a manual order.

Model Catalog Sync

Available since v7.61.1

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, claude, codex, gemini, iflow, kimi, kiro, qoder, qwen, xai, plus deprecated ghcp compatibility 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

Local OpenAI-Compatible Proxy

Manage the local Anthropic-compatible proxy for API profiles that point at OpenAI-compatible chat-completions endpoints:

# Start a local proxy for one profile
ccs proxy start hf

# Export the runtime environment for Claude-compatible clients
eval "$(ccs proxy activate hf)"
ccs proxy activate --fish

# Inspect or stop a running profile proxy
ccs proxy status hf
ccs proxy stop hf

Port behavior:

--port pins a one-off launch
proxy.profile_ports.<profile> pins a saved profile port
proxy.port guides the shared preferred starting port
otherwise CCS chooses an adaptive per-profile fallback

See OpenAI-Compatible Provider Routing.

Docker Deployment

Deploy CCS and CLIProxy as a Docker stack for team or server use.

# Build and start stack locally
ccs docker up

# Deploy remotely via SSH
ccs docker up --host <ssh-target>

# Stop and remove stack
ccs docker down

# Show compose + supervisor status
ccs docker status

# Tail combined logs
ccs docker logs

# Follow logs continuously
ccs docker logs --follow

# Update binaries in running container
ccs docker update

# Update binaries on remote container
ccs docker update --host <ssh-target>

# Show bundled paths and defaults
ccs docker config

# Show the current Docker CLIProxy API key
ccs docker show-key

# Remove the temporary legacy API key after client updates
ccs docker finalize-key-rotation

Examples:

# Deploy to remote server
ccs docker up --host user@myserver.com

# Follow logs after deploy
ccs docker logs --follow

# Update CLIProxy binary without restart
ccs docker update --host user@myserver.com

# Copy the active API key into a downstream client
ccs docker show-key --full

The ccs docker commands require Docker and Docker Compose on the target host. Remote deployment uses the SSH target alias from ~/.ssh/config.

Docker upgrades that replace the historical ccs-internal-managed API key keep that legacy key valid beside the new per-install key for a temporary grace window. The ccs docker up banner masks the new key; update clients with ccs docker show-key --full, then run ccs docker finalize-key-rotation when the old key is no longer needed. For already-broken upgrades, opt in explicitly with CCS_DOCKER_RESTORE_LEGACY_API_KEY=1.

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 Codex Switch) v7.61.1

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

Opens the visual configuration dashboard in your browser using the effective bind/port. By default CCS binds the dashboard to localhost. When the effective bind is reachable beyond loopback, CCS prints network URLs plus an auth reminder. If auth is disabled, remote users can still view read-only dashboard surfaces, but sensitive write routes stay localhost-only.

CCS Bar

ccs bar                    # Launch on the saved or first available port
ccs bar --port 3999        # Launch on, or safely move to, an exact port
ccs bar status             # Check the process record and HTTP reachability
ccs bar stop               # Safely stop the verified background process

--port requires an available integer from 1 to 65535. The selected port persists in the launch descriptor, so later launches try it first even after ccs bar stop. When moving a live server, CCS preflights the new port and restores the prior server if the replacement fails; failed restoration preserves the previous discovery and launch state for recovery. status distinguishes a stopped server, an invalid or stale process record, a live process with a failed HTTP probe, and a reachable server. stop signals a process only when its PID and recorded start identity still match. It removes server.pid and bar.json after a confirmed stop or stale process, but keeps them on identity mismatch, permission failure, signal failure, or timeout. Legacy PID-only server.pid files cannot prove process identity. Current CCS reports them as invalid and refuses to signal or clean them up. Confirm the CCS server process in Activity Monitor, or restart macOS, before moving the stale files aside; never signal the recorded number without verifying the process. See CCS Bar for installation, lifecycle details, and troubleshooting.

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 max
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 claude opus max
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.

Droid Runtime Target

Configure the default CLI target for Droid profiles:

# Route a profile to Droid at runtime
ccs glm --target droid

# Or use the ccsd shorthand
ccsd glm "your prompt"

# Set per-profile target in config
# config.yaml: profiles.my-profile.target: droid

Target values:

Target	Description
`claude`	Default — use Claude Code CLI
`droid`	Use Factory Droid CLI (`@factory/cli`)

The --target flag overrides the profile’s configured target and ccsd argv0 detection. See Droid Adapter for setup.

Official Channels Configuration

Configure Anthropic’s official Claude channels auto-enable for compatible Claude sessions:

# Show current Official Channels status
ccs config channels

# Select which official channels CCS should auto-enable
ccs config channels --set telegram,discord
ccs config channels --set all
ccs config channels --clear

# Optional unattended mode
ccs config channels --unattended
ccs config channels --no-unattended

# Save or clear per-channel bot tokens
ccs config channels --set-token telegram=<token>
ccs config channels --set-token discord=<token>
ccs config channels --clear-token telegram
ccs config channels --clear-token

Behavior:

Stores selected channels in ~/.ccs/config.yaml under channels
Stores TELEGRAM_BOT_TOKEN in ~/.claude/channels/telegram/.env
Stores DISCORD_BOT_TOKEN in ~/.claude/channels/discord/.env
Auto-adds --channels with any selected ready official plugins at runtime
Supported official channels: Telegram, Discord, and iMessage
Applies only to native Claude default and account sessions
Never auto-enables for API-key profiles, CLIProxy, Copilot, or Droid targets
--unattended maps to runtime --dangerously-skip-permissions only when auto-enable is active
Explicit user --channels or permission flags win over CCS defaults
iMessage is macOS-only and does not use a bot token

Manual Claude-side setup:

/plugin install telegram@claude-plugins-official
/telegram:configure <TELEGRAM_BOT_TOKEN>
/telegram:access pair <code>
/telegram:access policy allowlist

/plugin install discord@claude-plugins-official
/discord:configure <DISCORD_BOT_TOKEN>
/discord:access pair <code>
/discord:access policy allowlist

/plugin install imessage@claude-plugins-official
/imessage:access allow +15551234567

Image Analysis Configuration

Configure automatic image and PDF analysis for third-party launches:

# 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

# Set analysis timeout in seconds
ccs config image-analysis --timeout 120

# Set vision model for a specific provider
ccs config image-analysis --set-model agy gemini-2.5-flash
ccs config image-analysis --set-model codex gpt-5.1-codex-mini

# Set the fallback backend for bridge-backed profiles
ccs config image-analysis --set-fallback agy

# Override backend for a specific settings profile
ccs config image-analysis --set-profile-backend glm agy
ccs config image-analysis --clear-profile-backend glm

Default Behavior:

CCS uses a managed ImageAnalysis MCP tool when the runtime is healthy
Healthy launches suppress the legacy CCS image Read hook
CCS can fall back to compatibility hook behavior, then native Read, if the managed runtime is not usable
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

Browser Automation

Configure Claude Browser Attach and Codex Browser Tools:

# Setup and inspect browser automation
ccs help browser
ccs browser setup
ccs browser status
ccs browser doctor

# Control saved exposure policy
ccs browser policy
ccs browser policy --all manual
ccs browser enable claude
ccs browser disable codex

# Per-launch overrides
ccs glm --browser "inspect the app"
ccs glm --no-browser "summarize the docs"
ccs default --target codex --browser "use browser tools"

Behavior:

New installs keep both lanes disabled and manual
ccs browser setup is the primary remediation flow
ccs browser doctor is read-only
--browser opts in for one launch when the lane is enabled
--no-browser suppresses tooling for one launch

See Browser Automation.

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, xai, agy, kiro, kimi, qoder, 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`, `xai`, `agy`, `kiro`, `kimi`, `qoder`, `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 (Deprecated)

Copilot-specific subcommands remain available for existing deprecated GitHub Copilot compatibility setups:

ccs copilot <subcommand>

GitHub usage-based Copilot billing begins June 1, 2026. Prefer Codex or another active provider for new work.

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
`CCS_TARGET_ALIASES`	Unified alias map (e.g., `codex=mycodex`)
`CCS_CODEX_ALIASES`	Legacy comma-separated binary names for codex target

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 Commands

​Basic Usage

​Profile Commands

​Switch Profiles

​With Arguments

​Account Management

​Create Account Profile

​Bare Profiles

​List Profiles

​Show Profile

​Set Default

​Reset Default

​Remove Profile

​Shared Resources

​API Profile Management

​Basic Operations

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

​Using API Profiles

​OAuth Provider Commands

​Basic Usage

​Authentication

​Multi-Account

​Model Configuration

​GitLab Duo Auth Variants

​Multi-Account Management

​Logout

​Headless Mode

​Kiro-Specific Options

​Codex Reasoning Effort

​Cursor Provider And Legacy Bridge

​Droid Multi-Target Adapter

​Codex Runtime Target

​CLIProxy Management

​Lifecycle Commands

​Variant Management

​Quota Management

​Routing Strategy

​Pool Routing

​Account Drain Order

​Model Catalog Sync

​Remote Proxy Configuration

​Local OpenAI-Compatible Proxy

​Docker Deployment

​Migration Commands

​Utility Commands

​Version

​Help

​Update

​Configuration Dashboard

​CCS Bar

​Dashboard Authentication CLI

​Claude IDE Extension Setup

​Thinking Configuration

​Droid Runtime Target

​Official Channels Configuration

​Image Analysis Configuration

​Browser Automation

​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 (Deprecated)

​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

Show Profile

Set Default

Reset Default

Remove Profile

Shared Resources

API Profile Management

Basic Operations

Profile Lifecycle (Discover, Copy, Export, Import)

Using API Profiles

OAuth Provider Commands

Basic Usage

Authentication

Multi-Account

Model Configuration

GitLab Duo Auth Variants

Multi-Account Management

Logout

Headless Mode

Kiro-Specific Options

Codex Reasoning Effort

Cursor Provider And Legacy Bridge

Droid Multi-Target Adapter

Codex Runtime Target

CLIProxy Management

Lifecycle Commands

Variant Management

Quota Management

Routing Strategy

Pool Routing

Account Drain Order

Model Catalog Sync

Remote Proxy Configuration

Local OpenAI-Compatible Proxy

Docker Deployment

Migration Commands

Utility Commands

Version

Help

Update

Configuration Dashboard

CCS Bar

Dashboard Authentication CLI

Claude IDE Extension Setup

Thinking Configuration

Droid Runtime Target

Official Channels Configuration

Image Analysis Configuration

Browser Automation

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 (Deprecated)

Copilot Usage Quota

Environment Variables

Core Configuration

Remote Proxy Configuration

Thinking

Droid / Multi-Target

Advanced Options

Configuration Paths

Shared Data Structure

Exit Codes