Skip to main content

​
CLI Flags Reference

Complete reference for all CLI flags available in CCS. Flags can be combined with profile names and commands.

​
Overview

CCS CLI flags provide runtime configuration for authentication, proxy behavior, and provider-specific features. Flags override config file settings and follow this priority: CLI Flags > Environment Variables > config.yaml > Defaults

​
Account Management Flags

Manage multiple OAuth accounts for CLIProxy providers (gemini, codex, agy, qwen, iflow, kiro, ghcp).

​
--use <account>

Scope: All OAuth providers Purpose: Switch active account for profile execution Priority: HIGH 
ccs codex --use work@example.com
ccs qwen --use personal@gmail.com
Behavior:
  • Temporarily uses specified account instead of default
  • Does NOT change default account in config
  • Account must exist (use --accounts to list)
  • Nickname or email accepted
Related: --accounts, --nickname, ccs auth default

​
--accounts

Scope: All OAuth providers Purpose: List all registered accounts with metadata Priority: HIGH 
ccs codex --accounts
ccs kiro --accounts
Output:
  • Email addresses
  • Nicknames (if set)
  • Last used timestamp
  • Default account indicator
Related: --use, ccs auth list

​
--nickname <name>

Scope: All OAuth providers Purpose: Rename account with human-friendly alias Priority: MEDIUM 
ccs codex --nickname work
ccs codex --use bob@company.com --nickname work-bob
Behavior:
  • Sets nickname for current/specified account
  • Nickname stored in config.yaml under cliproxy.oauth_accounts
  • Can use nickname in --use flag after setting
  • Must be unique across accounts
Related: --use, --accounts

​
--auth

Scope: All OAuth providers Purpose: Manually trigger OAuth flow Priority: MEDIUM 
ccs codex --auth           # Re-authenticate default account
ccs kiro --auth --add       # Add new account
Behavior:
  • Opens browser for OAuth flow
  • Refreshes expired tokens
  • Updates credentials in CLIProxy session storage
  • Shows success/error message
Use Cases:
  • Token expired or revoked
  • Session became invalid
  • Testing authentication
Related: --logout, --add

​
--logout

Scope: All OAuth providers Purpose: Remove account credentials and session Priority: MEDIUM 
ccs codex --logout
ccs qwen --use old@example.com --logout
Behavior:
  • Removes OAuth tokens from session storage
  • Does NOT remove account from config.yaml
  • Requires re-authentication on next use
  • Safe to run multiple times
Related: --auth, ccs auth remove

​
--add (with —auth)

Scope: All OAuth providers Purpose: Add new account while keeping existing Priority: MEDIUM 
ccs codex --auth --add
ccs kiro --auth --add --nickname work-alt
Behavior:
  • Opens browser for new OAuth flow
  • Adds account to config.yaml
  • Does NOT replace existing accounts
  • Can set nickname immediately
Related: --auth, --nickname, ccs auth create

​
Remote Proxy Flags

Configure connection to remote CLIProxyAPI server instead of local binary.

​
--proxy-host

Scope: CLIProxy profiles and variants Purpose: Remote proxy hostname or IP Priority: HIGH 
ccs codex --proxy-host proxy.example.com
ccs codex --proxy-host 192.168.1.100
Behavior:
  • Overrides config.cliproxy_server.remote.host
  • Requires valid hostname/IP (no protocol prefix)
  • Auto-detects protocol if port 443 (HTTPS) or 80 (HTTP)
  • Falls back to local if unreachable (unless --remote-only)
Related: --proxy-port, --proxy-protocol, CCS_PROXY_HOST

​
--proxy-port

Scope: CLIProxy profiles and variants Purpose: Remote proxy port number Priority: HIGH 
ccs codex --proxy-host proxy.example.com --proxy-port 8443
ccs codex --proxy-host 192.168.1.100 --proxy-port 80
Behavior:
  • Overrides config.cliproxy_server.remote.port
  • Defaults: 443 (HTTPS), 80 (HTTP) if not specified
  • Must be valid port (1-65535)
Related: --proxy-host, CCS_PROXY_PORT

​
--proxy-auth-token

Scope: CLIProxy profiles and variants Purpose: Authentication token for remote proxy Priority: HIGH 
ccs codex --proxy-host proxy.example.com --proxy-auth-token <token>
Behavior:
  • Overrides config.cliproxy_server.remote.auth_token
  • Sent in Authorization header
  • Required if remote proxy has auth enabled
  • Can be API key or JWT
Security: Do NOT commit tokens to version control Related: --proxy-host, CCS_PROXY_AUTH_TOKEN

​
--proxy-protocol

Scope: CLIProxy profiles and variants Purpose: Remote proxy protocol (http/https) Priority: MEDIUM 
ccs codex --proxy-host proxy.example.com --proxy-protocol https
Behavior:
  • Overrides config.cliproxy_server.remote.protocol
  • Values: http, https
  • Default: http (unless port 443)
  • When set to https: Automatically starts HTTP→HTTPS tunnel (see Remote Proxy HTTPS Tunnel)
Related: --proxy-host, CCS_PROXY_PROTOCOL, --allow-self-signed

​
--proxy-timeout

Scope: CLIProxy profiles and variants Purpose: Health check timeout in milliseconds Priority: LOW 
ccs codex --proxy-host proxy.example.com --proxy-timeout 5000
Behavior:
  • Overrides config.cliproxy_server.remote.timeout
  • Default: 2000ms (2 seconds)
  • Used for initial health check only
  • Higher values for slow networks
Related: --proxy-host, CCS_PROXY_TIMEOUT

​
--local-proxy

Scope: CLIProxy profiles and variants Purpose: Force local CLIProxy mode Priority: MEDIUM 
ccs codex --local-proxy
Behavior:
  • Disables remote proxy even if configured
  • Spawns local CLIProxyAPI binary
  • Useful for testing or offline work
  • Ignores config.cliproxy_server.remote settings
Related: --remote-only, --proxy-host

​
--remote-only

Scope: CLIProxy profiles and variants Purpose: Fail if remote proxy unreachable Priority: MEDIUM 
ccs codex --proxy-host proxy.example.com --remote-only
Behavior:
  • Disables fallback to local proxy
  • Exit with PROXY_ERROR if remote unreachable
  • Useful for enforcing remote proxy usage
  • Overrides config.cliproxy_server.fallback.enabled
Related: --local-proxy, --proxy-host

​
--allow-self-signed

Scope: CLIProxy profiles and variants Purpose: Accept self-signed SSL certificates Priority: LOW 
ccs codex --proxy-host proxy.example.com --proxy-protocol https --allow-self-signed
Behavior:
  • Disables SSL certificate validation
  • Required for dev/test environments with self-signed certs
  • Security Risk: Only use in trusted environments
Related: --proxy-protocol, CCS_ALLOW_SELF_SIGNED

​
--target <cli>

Scope: All supported profiles except cliproxy, copilot, and account Purpose: Route profile to alternative CLI target Priority: HIGH 
ccs glm --target droid       # Route to Droid CLI
ccs codex --target=droid     # Supports both formats
ccs glm --target claude      # Explicit Claude (default)
Behavior:
  • claude (default): Launch via Claude Code CLI
  • droid: Launch via Droid CLI (@factory/cli)
  • Overrides per-profile target config and argv0 detection
  • Binary located via CCS_DROID_PATH or PATH lookup
  • Legacy glmt compatibility profiles follow the normal settings-profile target flow after runtime normalization
Related: CCS_DROID_PATH, CCS_DROID_ALIASES, Droid Adapter

​
--permission-mode <mode> (persist)

Scope: All profiles Purpose: Set Claude permission mode (persisted to session) Priority: HIGH 
ccs codex --permission-mode bypassPermissions
ccs glm --permission-mode plan
ccs claude --permission-mode acceptEdits
Valid values: default, plan, acceptEdits, bypassPermissions Related: --dangerously-skip-permissions, --auto-approve

​
--dangerously-skip-permissions / --auto-approve

Scope: All profiles Purpose: Equivalent to --permission-mode bypassPermissions Priority: HIGH 
ccs codex --dangerously-skip-permissions
ccs codex --auto-approve    # Alias
Behavior: Bypasses all Claude permission prompts. Use with caution in automated environments.

​
--kimi

Scope: /ccs delegation command Purpose: Force Kimi OAuth (CLIProxy) for long context Priority: MEDIUM 
/ccs --kimi "analyze large codebase"
Behavior: Delegation flag — routes request through Kimi OAuth provider when long context is needed.

​
--km

Scope: /ccs delegation command Purpose: Force Kimi API key (direct) for long context Priority: MEDIUM 
/ccs --km "analyze large codebase"
Behavior: Delegation flag — routes request through Kimi for Coding API (ccs km) when long context is needed.

​
--thinking <value>

Scope: All profiles Purpose: Enable extended thinking mode Priority: HIGH (overrides CCS_THINKING env and config) 
ccs claude --thinking 20000      # 20k token budget
ccs claude --thinking high       # Level name
ccs codex --thinking off         # Disable thinking
Behavior:
  • Enables extended thinking for compatible models (Claude Sonnet 4.5+, Gemini 2.0+)
  • Accepts token budget number (e.g., 5000, 20000) or level name (minimal, low, medium, high, xhigh, auto)
  • Off values: off, none, disabled, 0 — all equivalent, disable thinking
  • Overrides CCS_THINKING env var and thinking config section
  • Ignored by models without thinking support
Related: CCS_THINKING env var, ccs config thinking, Extended Thinking

​
--1m / --no-1m

Scope: All profiles Purpose: Enable/disable 1M token extended context window Priority: MEDIUM 
ccs claude --1m "analyze large codebase"      # Enable 1M context
ccs claude --no-1m "quick summary"            # Disable 1M context
ccs claude --1m                               # Interactive with 1M enabled
Behavior:
  • --1m: Enables 1M token context window via [1m] model suffix
  • --no-1m: Disables 1M token context window (removes [1m] suffix)
  • Auto-enabled: Native Gemini models (e.g., gemini-3-pro) have 1M enabled by default
  • Opt-in: Claude models require explicit --1m flag to use extended context
  • Overrides: CLI flag takes priority over provider config settings
  • Warning: Shows warning if model doesn’t support extended context
Supported Models:
  • Claude Opus 4.6 (auto-detect from model catalog)
  • Claude Sonnet 4.5 (with —1m flag)
  • Gemini 3 Pro (auto-enabled)
  • Gemini 2.0 (auto-enabled)
Technical Details:
  • Extended context uses model suffix format: claude-opus-4-6[1m]
  • Requires compatible Claude Code version supporting [1m] suffix
  • Token budget remains 1M even if context window is smaller
Related: Extended context feature, model catalogs, provider documentation

​
--headless

Scope: OAuth providers (gemini, codex, agy, kiro, etc.) Purpose: OAuth without browser, display URL for manual authentication Priority: LOW 
ccs kiro --auth --headless
ccs codex --auth --add --headless
Behavior:
  • Skips automatic browser launch during OAuth
  • Displays OAuth URL in terminal for manual copying
  • Useful for SSH sessions without browser access
  • User opens URL in external browser, completes auth
  • CCS waits for callback on local server
Use Cases:
  • Remote SSH sessions
  • CI/CD environments without browser
  • Headless servers
Related: --auth, --incognito

​
--incognito

Scope: Kiro provider Purpose: Force incognito browser mode for OAuth Priority: LOW 
ccs kiro --auth --incognito
Behavior:
  • Opens browser in incognito/private mode
  • Prevents cookie/session persistence
  • Opposite of --no-incognito flag
  • Useful for testing or multi-account isolation
Related: --no-incognito, --auth

​
Provider-Specific Flags

Flags available only for specific providers.

​
--backend <type> (CLIProxy only)

Scope: CLIProxy providers (gemini, codex, agy, qwen, iflow, kiro, ghcp) Purpose: Override CLIProxy backend selection Priority: HIGH 
ccs codex --backend=original   # Use CLIProxyAPI
ccs kiro --backend=plus        # Required for kiro/ghcp
Behavior:
  • Overrides config.cliproxy.backend setting
  • Values: original | plus
  • Plus required for kiro/ghcp providers
  • Backend-specific binaries auto-downloaded if needed
Use Cases:
  • Test different backends without changing config
  • Force specific backend for troubleshooting
  • Ensure kiro/ghcp compatibility
Related: config.cliproxy.backend, provider compatibility

​
--import (Kiro only)

Scope: Kiro provider Purpose: Import OAuth token from Kiro IDE Priority: HIGH 
ccs kiro --import
Behavior:
  • Reads token from Kiro IDE config location
  • Bypasses browser OAuth flow
  • Faster authentication if IDE already logged in
  • Falls back to browser if import fails
Requirements:
  • Kiro IDE installed and authenticated
  • Token file accessible
Related: --auth, Kiro provider docs

​
--config (Supported providers)

Scope: Catalog-backed CLIProxy providers (agy, claude, codex, gemini, kimi) Purpose: Launch interactive model configuration UI Priority: MEDIUM 
ccs codex --config
Behavior:
  • Opens terminal UI for model selection
  • Shows available models with metadata
  • Updates config.yaml with selected model
  • Validates model availability
Related: Gemini provider docs

​
--no-incognito (Kiro only)

Scope: Kiro provider Purpose: Use normal browser mode instead of incognito Priority: MEDIUM 
ccs kiro --no-incognito
Behavior:
  • Opens browser in normal mode (saves cookies/session)
  • Useful for persistent AWS SSO login
  • Overrides config.cliproxy.kiro_no_incognito
  • Browser profile persists between sessions
Use Case: Avoid re-entering AWS credentials for Kiro authentication Related: config.cliproxy.kiro_no_incognito

​
CLIProxy Diagnostic Flags

Flags for debugging CLIProxy behavior and quota fetching.

​
--verbose, -v

Scope: CLIProxy commands (ccs cliproxy, provider commands) Purpose: Enable detailed diagnostics Priority: LOW 
ccs cliproxy status --verbose
ccs codex --verbose
Output includes:
  • Token refresh attempts with timestamps
  • Project ID resolution details
  • Model quota API calls and responses
  • Error details with HTTP status codes
Use Cases:
  • Debugging quota fetch failures
  • Investigating token refresh issues
  • Troubleshooting “N/A (fetch unavailable)” quota display
Related: ccs cliproxy status, ccs cliproxy quota, GLMT Deprecation

​
Persist Command Flags

Flags for the ccs persist command that manages settings.json persistence.

​
--yes, -y

Scope: persist command Purpose: Skip confirmation prompts, auto-backup before modification Priority: MEDIUM 
ccs persist glm --yes
ccs persist glm -y
Behavior:
  • Skips interactive confirmation
  • Automatically creates backup before changes
  • Useful for automation and scripts
Related: ccs persist, --list-backups, --restore

​
--list-backups

Scope: persist command Purpose: List all available settings.json backup files Priority: LOW 
ccs persist --list-backups
Output: 
Available backups:
  [latest] 20260114_120534 (2026-01-14 12:05:34)
           20260113_093021 (2026-01-13 09:30:21)
           20260112_155612 (2026-01-12 15:56:12)

To restore: ccs persist --restore [timestamp]
Related: --restore, ccs persist

​
--restore [timestamp]

Scope: persist command Purpose: Restore settings.json from backup Priority: MEDIUM 
# Restore from latest backup
ccs persist --restore

# Restore from specific backup
ccs persist --restore 20260113_093021
Behavior:
  • Validates JSON integrity before restore
  • Rejects symlinked backup files (security)
  • Creates backup of current settings before restore
  • Confirms restore success with timestamp
Use Cases:
  • Recovering from incorrect persist operation
  • Reverting to known-good configuration
  • Testing configuration changes safely
Related: --list-backups, ccs persist

​
Flag Combinations

Common flag combinations for typical workflows.

​
Multi-Account Workflow

# List accounts
ccs codex --accounts

# Switch account for single run
ccs codex --use work@example.com

# Add new account with nickname
ccs codex --auth --add --nickname personal

# Use new account
ccs codex --use personal

​
Remote Proxy Setup

# Basic remote proxy
ccs codex --proxy-host proxy.example.com --proxy-port 8443 --proxy-auth-token <token>

# HTTPS with self-signed cert
ccs codex --proxy-host proxy.example.com --proxy-protocol https --allow-self-signed

# Remote-only (no fallback)
ccs codex --proxy-host proxy.example.com --remote-only

​
Provider-Specific Workflows

# Kiro with token import and persistent browser
ccs kiro --import --no-incognito

# Codex with model configuration
ccs codex --config

​
Diagnostic & Persist Workflows

# Verbose CLIProxy diagnostics
ccs cliproxy status --verbose
ccs codex --verbose

# Persist settings with auto-confirmation
ccs persist glm --yes

# List and restore from backups
ccs persist --list-backups
ccs persist --restore 20260113_093021

​
Environment Variable Equivalents

Many flags have environment variable equivalents for persistent configuration.
FlagEnvironment VariableConfig Key
--proxy-hostCCS_PROXY_HOSTcliproxy_server.remote.host
--proxy-portCCS_PROXY_PORTcliproxy_server.remote.port
--proxy-auth-tokenCCS_PROXY_AUTH_TOKENcliproxy_server.remote.auth_token
--proxy-protocolCCS_PROXY_PROTOCOLcliproxy_server.remote.protocol
--proxy-timeoutCCS_PROXY_TIMEOUTcliproxy_server.remote.timeout
--allow-self-signedCCS_ALLOW_SELF_SIGNEDN/A
--no-incognitoN/Acliproxy.kiro_no_incognito
--target droidCCS_DROID_ALIASES (argv0) / CCS_DROID_PATHprofiles.<name>.target
--thinkingCCS_THINKINGthinking.override
Priority: CLI flags override environment variables override config file

​
Droid/Target Environment Variables

VariableDescription
CCS_DROID_ALIASESComma-separated argv0 binary names that map to droid target
CCS_DROID_PATHExplicit absolute path to the droid binary

​
Thinking Environment Variable

VariableAccepted Values
CCS_THINKINGminimal, low, medium, high, xhigh, auto, off, none, disabled, 0, or integer 0–100000

​
Troubleshooting

​
Account Flags

“Account not found” error:
  • Run ccs <profile> --accounts to list available accounts
  • Check spelling of email/nickname
  • Verify account was created with --auth --add
Nickname conflicts:
  • Nicknames must be unique across all accounts
  • Remove old nickname before setting new one
  • Edit config.yaml manually if needed

​
Remote Proxy Flags

Connection timeout:
  • Increase --proxy-timeout value
  • Check network connectivity to host
  • Verify host/port are correct
  • Try --local-proxy to test locally
SSL certificate errors:
  • Use --allow-self-signed for dev/test environments
  • Verify certificate is valid in production
  • Check --proxy-protocol is https
Authentication failures:
  • Verify --proxy-auth-token is correct
  • Check token hasn’t expired
  • Test token with curl or similar tool