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 gemini --use work@example.com
ccs agy --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 gemini --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 gemini --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 gemini --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 gemini --logout
ccs agy --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 gemini --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: All profiles Purpose: Remote proxy hostname or IP Priority: HIGH 
ccs gemini --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: All profiles Purpose: Remote proxy port number Priority: HIGH 
ccs gemini --proxy-host proxy.example.com --proxy-port 8443
ccs agy --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: All profiles Purpose: Authentication token for remote proxy Priority: HIGH 
ccs gemini --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: All profiles Purpose: Remote proxy protocol (http/https) Priority: MEDIUM 
ccs gemini --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: All profiles Purpose: Health check timeout in milliseconds Priority: LOW 
ccs gemini --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: All profiles Purpose: Force local CLIProxy mode Priority: MEDIUM 
ccs gemini --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: All profiles Purpose: Fail if remote proxy unreachable Priority: MEDIUM 
ccs gemini --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: All profiles Purpose: Accept self-signed SSL certificates Priority: LOW 
ccs gemini --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

​
--thinking <value>

Scope: All profiles Purpose: Enable extended thinking mode Priority: MEDIUM 
ccs gemini --thinking 20000      # 20k token budget
ccs agy --thinking high          # Level name
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 (low, medium, high)
  • Overrides profile’s default thinking budget
  • Ignored by models without thinking support
Related: Provider-specific thinking capabilities

​
--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 gemini --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 gemini --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 (Gemini only)

Scope: Gemini provider Purpose: Launch interactive model configuration UI Priority: MEDIUM 
ccs gemini --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 quota fetch and token refresh diagnostics Priority: LOW 
ccs cliproxy status --verbose
ccs agy --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

​
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 gemini --accounts

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

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

# Use new account
ccs gemini --use personal

​
Remote Proxy Setup

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

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

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

​
Provider-Specific Workflows

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

# Gemini with model configuration
ccs gemini --config

​
Diagnostic & Persist Workflows

# Verbose CLIProxy diagnostics
ccs cliproxy status --verbose
ccs agy --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
Priority: CLI flags override environment variables override config file

​
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