> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Commands

> Complete reference for CCS commands

# CLI Commands

Complete reference for all CCS commands and options.

## Basic Usage

```bash theme={null}
ccs [profile] [args...]
```

* `profile` - Optional profile name (default: "default")
* `args` - Passed directly to Claude CLI

## Profile Commands

### Switch Profiles

```bash theme={null}
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
```

<Note>
  `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.
</Note>

### With Arguments

```bash theme={null}
ccs glm --verbose
ccs /plan "add feature"
ccs glm /code "implement feature"
```

## Account Management

### Create Account Profile

```bash theme={null}
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:

```bash theme={null}
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 normal `settings.json` with `~/.claude/settings.json`; history sharing is
separate and only happens when accounts use shared mode and the same context
group.

#### Bare Profiles

```bash theme={null}
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

```bash theme={null}
ccs auth list
```

Shows all configured profiles with their status.

### Show Profile

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
ccs auth reset-default
```

Restores the original CCS default profile.

### Remove Profile

```bash theme={null}
ccs auth remove <name> --force
```

Removes profile and deletes instance directory.

### Shared Resources

```bash theme={null}
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, 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

```bash theme={null}
# 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)

<Note>Available since v7.52.0</Note>

```bash theme={null}
# 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

```bash theme={null}
# 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` · `gemini` · `iflow` · `kimi` · `kiro` · `cursor` · `gitlab` · `codebuddy` · `kilo` · `qoder`

Deprecated compatibility shortcut: `ghcp`

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

```bash theme={null}
ccs codex "your prompt"
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

```bash theme={null}
ccs codex --auth         # Auth only, no session
ccs codex --auth --add   # Add another account
```

### Multi-Account

```bash theme={null}
ccs codex --accounts     # List all accounts
ccs codex --use <name>   # Switch to account
```

### Model Configuration

```bash theme={null}
ccs codex --config       # Change model (interactive)
ccs kimi --config        # Change model (interactive)
```

### GitLab Duo Auth Variants

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
ccs codex --logout       # Clear cached tokens
ccs kiro --logout
```

### Headless Mode

```bash theme={null}
ccs codex --headless     # No browser, get URL for remote auth
```

### Kiro-Specific Options

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
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`.

```bash theme={null}
# 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:

```bash theme={null}
# 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`:**

```bash theme={null}
ln -s $(which ccs) /usr/local/bin/ccsd
```

See [Droid Adapter](/features/workflow/droid-adapter) for full documentation.

## Codex Runtime Target

<Note>Available since v7.62.0</Note>

Route profiles to the native Codex CLI:

```bash theme={null}
# 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:**

```bash theme={null}
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](/features/workflow/codex-adapter) for full documentation.

## CLIProxy Management

Manage the CLIProxyAPI binary:

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
# 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.

```bash theme={null}
# 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:

```bash theme={null}
# 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](/features/pool) for the full guide.

```bash theme={null}
# 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
```

<Note>
  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](/features/pool#leaving-a-pool).
</Note>

### Account Drain Order

Control the order accounts are drained in within a provider:

```bash theme={null}
# 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
```

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

### Model Catalog Sync

<Note>Available since v7.61.1</Note>

Sync remote model catalogs from CLIProxyAPI with static fallback catalogs:

```bash theme={null}
# 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`, `iflow`,
`kiro`, `ghcp`, `kimi`

**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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](/features/proxy/openai-compatible-providers).

## Docker Deployment

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

```bash theme={null}
# 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:**

```bash theme={null}
# 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
```

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

<Note>
  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`.
</Note>

## Migration Commands

Migrate to unified configuration format:

```bash theme={null}
# Trigger manual migration
ccs migrate

# Show migration help
ccs migrate --help
```

<Note>
  Migrations run automatically on first launch after updates. Use `ccs migrate`
  to manually trigger or re-run migrations.
</Note>

## Utility Commands

### Version

```bash theme={null}
ccs --version
```

Shows CCS version and installation details:

```
CCS (Claude Code Switch) v7.61.1

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

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

### Help

```bash theme={null}
ccs --help
```

Shows comprehensive usage documentation.

### Update

```bash theme={null}
ccs update              # Standard update
ccs update --force      # Force reinstall
ccs update --beta       # Install beta channel
ccs update --force --beta  # Force beta install
```

### Configuration Dashboard

```bash theme={null}
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.

### Dashboard Authentication CLI

Configure optional login protection for the dashboard:

```bash theme={null}
# 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

<Note>
  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.
</Note>

<Warning>
  If you expose the dashboard beyond localhost, protect it first with `ccs
      config auth setup`.
</Warning>

### Claude IDE Extension Setup

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

```bash theme={null}
# 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:

```bash theme={null}
# 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](/features/ai/extended-thinking) for full documentation.

### Droid Runtime Target

Configure the default CLI target for Droid profiles:

```bash theme={null}
# 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`) |

<Note>
  The `--target` flag overrides the profile's configured target and `ccsd`
  argv0 detection. See [Droid Adapter](/features/workflow/droid-adapter) for setup.
</Note>

### Official Channels Configuration

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

```bash theme={null}
# 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:**

```bash theme={null}
/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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](/features/workflow/browser-automation).

### Health Check

```bash theme={null}
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

```bash theme={null}
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

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

### Cleanup

```bash theme={null}
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).

```bash theme={null}
# 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, 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:

```bash theme={null}
# 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

```bash theme={null}
# 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.).

```bash theme={null}
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`, `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:**

```bash theme={null}
# 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)
```

<Note>
  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.
</Note>

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

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

```bash theme={null}
ccs --shell-completion
ccs -sc
```

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

### Token Management

```bash theme={null}
ccs tokens
```

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

## Headless Delegation

Execute prompts without interactive session:

```bash theme={null}
ccs -p "your prompt"
ccs --prompt "your prompt"
ccs glm -p "implement feature"
```

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

## Copilot Commands (Deprecated)

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

```bash theme={null}
ccs copilot <subcommand>
```

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

### Copilot Usage Quota

```bash theme={null}
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)
```

<Note>
  On Windows, copies are used instead of symlinks if symlinks are unavailable.
</Note>

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