CLI Command Reference
Relevant source files
The following files were used as context for generating this wiki page:
The CCS CLI is a multi-provider profile and runtime manager designed to streamline the use of Claude Code and compatible runtimes. It provides a stable command surface for switching between isolated account contexts, OAuth providers (such as Codex, Gemini, and Kiro), and API-based profiles like GLM or Ollama without manual configuration modification.
The CLI acts as a dispatcher that resolves profiles and targets before executing the appropriate adapter or command handler. It supports features such as browser automation, long-context (1m) model overrides, and native runtime bridges for Factory Droid and Codex. Sources: README.md:1-20, src/ccs.ts:25-50
Core Command Structure
The CLI uses a tiered command structure categorized by the intent of the operation. Commands are grouped into "Start Here" for execution, "Profile Management" for configuration, "Compatible Runtimes" for target-specific bridges, and "Operations" for system maintenance. Sources: src/commands/help-command.ts:40-55
General Usage Syntax
ccs <profile> [claude-args...] # Launch a profile with Claude Code
ccs <command> [options] # Execute a management command
ccs help <topic> # View specific help documentation
Sources: src/commands/help-command.ts:213-217
Primary Command Groups
| Group | Purpose | Key Commands |
|---|---|---|
| Start Here | Initial setup and core execution | setup, auth, config |
| Profile Management | Lifecycle of API and OAuth profiles | api, cliproxy, env, migrate |
| Compatible Runtimes | Bridging to specific CLI environments | browser, cursor, copilot |
| Operations | System health and maintenance | doctor, cleanup, tokens, docker |
Sources: src/commands/help-command.ts:45-55, AGENTS.md:65-80
Execution Flow and Dispatching
The CCS entry point manages a multi-phase dispatching logic to ensure the correct environment is prepared for the requested profile.
The CLI uses a singleton wiring system to register target adapters (Claude, Droid, and Codex) during Phase A of execution. Sources: src/ccs.ts:25-30, src/ccs.ts:40-75
API Profile Management (ccs api)
The api command handles the creation and management of profiles backed by custom API endpoints or provider presets.
Profile Creation (ccs api create)
When creating a profile, the CLI can use pre-defined presets (e.g., Anthropic, GLM, Kimi) or interactive prompts to gather base_url, api_key, and model mappings. Sources: src/commands/api-command/create-command.ts:320-350
- Model Mapping: Supports mapping different models for
opus,sonnet, andhaikutiers. - Long Context: Includes an
--1mflag to opt-in to 1-million token extended context for compatible Claude models. Sources: src/commands/api-command/create-command.ts:255-275
Provider Shortcut Commands
Common OAuth providers have direct command shortcuts that bypass standard api syntax:
ccs geminiccs codexccs gitlabccs kiro(Supports AWS Builder ID and IAM Identity Center flows)
Sources: src/commands/help-command.ts:135-150, src/commands/help-command.ts:175-195
Browser Automation (ccs browser)
The browser system manages two distinct lanes: Claude Browser Attach (using local Chrome sessions) and Codex Browser Tools (using Playwright MCP overrides). Sources: src/commands/browser-command.ts:60-70
Configuration & Policy
Users can define a BrowserToolPolicy as either auto or manual. In manual mode, browser tools are hidden unless the --browser flag is explicitly passed during launch. Sources: src/commands/browser-command.ts:35-45
| Subcommand | Description |
|---|---|
setup | Configures user-data directories and remote debugging ports |
status | Checks readiness of Claude and Codex browser lanes |
doctor | Identifies missing dependencies or configuration errors |
policy | Displays or updates the default exposure policy |
Sources: src/commands/browser-command.ts:46-60
System Diagnostics and Global Flags
The CLI provides built-in tools for maintaining the health of the multi-provider environment.
The Doctor Command
The ccs doctor command performs a multi-step check of the installation, including:
- Checking for
bin/ccs.jsand executable permissions. - Verifying the existence of
.claude/commands/ccs.mdand skills. - Testing TTY detection and
NO_COLORrespect.
Sources: tests/native/unix/install.sh:80-100, tests/integration/ux-integration-test.sh:160-175
Global Execution Flags
-v, --version: Displays the current version of the CCS CLI.-sc, --shell-completion: Installs shell completion for Bash, Zsh, Fish, or PowerShell.--target <cli>: Overrides the default runtime target (e.g., forcing a profile to run ondroid).--effort <level>: Overrides native Claude session effort/thinking budget (minimal, low, medium, high, max).
Sources: src/commands/help-command.ts:240-245, src/config/loader/yaml-serializer.ts:220-235
Summary
The CCS CLI acts as the central orchestration layer for AI developer tools, abstracting the complexity of multi-account and multi-provider configurations. By utilizing a robust adapter pattern and interactive creation flow, it enables developers to switch between local models, specialized OAuth providers, and standard Anthropic subscriptions while maintaining a consistent user experience. Sources: README.md:25-45, src/ccs.ts:45-60