> ## 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 Flags Reference

> Complete reference for all CCS CLI flags including account management, remote proxy configuration, and provider-specific options

# 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`, `iflow`, `kiro`, `claude`, `kimi`, `cursor`, `gitlab`,
`codebuddy`, `kilo`) plus deprecated `ghcp` compatibility.

### `--use <account>`

**Scope:** All OAuth providers
**Purpose:** Switch active account for profile execution
**Priority:** HIGH

```bash theme={null}
ccs codex --use work@example.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

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

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

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

```bash theme={null}
ccs codex --logout
ccs kimi --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

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

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

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

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

```bash theme={null}
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](/features/proxy/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

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

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

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

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

***

## Browser Automation Flags

### `--browser`

**Scope:** Claude-target and Codex-target launches
**Purpose:** Expose configured browser tooling for this launch
**Priority:** HIGH

```bash theme={null}
ccs glm --browser "inspect the page"
ccs default --target codex --browser "use browser tools"
```

**Behavior:**

* Forces browser tooling on for the current launch when that lane is enabled
* Does not change saved `browser.<lane>.policy`
* Fails safe with guidance if the selected lane is disabled or not ready

**Related:** `ccs browser setup`, [Browser Automation](/features/workflow/browser-automation)

***

### `--no-browser`

**Scope:** Claude-target and Codex-target launches
**Purpose:** Suppress configured browser tooling for this launch
**Priority:** HIGH

```bash theme={null}
ccs glm --no-browser "summarize the docs"
```

**Behavior:**

* Keeps browser tooling hidden for the current launch even when policy is `auto`
* Useful for privacy-sensitive runs or quick non-browser tasks
* Cannot be combined with `--browser`

**Related:** `browser.claude.policy`, `browser.codex.policy`

***

## Runtime Target Flags

### `--target <cli>`

**Scope:** All supported profiles except `cliproxy`, `copilot`, and `account`
**Purpose:** Route profile to alternative CLI target
**Priority:** HIGH

```bash theme={null}
ccs glm --target droid       # Route to Droid CLI
ccs codex --target codex     # Route to native Codex 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`)
* `codex`: Launch via native Codex CLI (transient credentials, no file rewrites)
* `ccsxp` shortcut: Forces `ccs codex --target codex`, strips any user `--target` override
* Overrides per-profile `target` config and argv0 detection
* Binary located via `CCS_DROID_PATH` or PATH lookup (droid), or PATH lookup (codex)
* Legacy `glmt` compatibility profiles follow the normal settings-profile target flow after runtime normalization

**Related:** `CCS_DROID_PATH`, `CCS_DROID_ALIASES`, `CCS_TARGET_ALIASES`, [Droid Adapter](/features/workflow/droid-adapter), [Codex Adapter](/features/workflow/codex-adapter)

***

### `--permission-mode <mode>` (persist)

**Scope:** All profiles
**Purpose:** Set Claude permission mode (persisted to session)
**Priority:** HIGH

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

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

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

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

```bash theme={null}
ccs claude --thinking 20000      # 20k token budget
ccs claude --thinking high       # Level name
ccs claude --thinking max        # Adaptive ceiling on supported models
ccs codex --thinking off         # Disable thinking
```

**Behavior:**

* Enables extended thinking for compatible models
* Accepts token budget number (e.g., 5000, 20000) or level name (minimal, low, medium, high, xhigh, max, auto)
* `max` stays distinct on models that expose it, such as Claude Fable 5 and Opus 4.8; models without a native max level map it to their supported ceiling
* 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
* Native Claude one-session effort overrides are documented separately under
  `--effort`

**Related:** `CCS_THINKING` env var, `ccs config thinking`, [Extended Thinking](/features/ai/extended-thinking)

***

### `--effort <value>`

**Scope:** Native Claude launches, plus Codex compatibility flows
**Purpose:** Apply a one-session reasoning effort override
**Priority:** HIGH

```bash theme={null}
ccs --effort high "debug this"
ccs work --effort max "review this architecture"
ccs codex --effort xhigh "deep analysis"
```

**Behavior:**

* On native Claude launches, CCS validates `low|medium|high|xhigh|max`,
  normalizes the value, and forwards it without mutating Claude or CCS config
  files
* On Codex and other CCS thinking flows, `--effort` remains a compatibility
  alias of `--thinking`
* Missing or invalid values fail fast before the runtime is spawned

**Related:** `--thinking`, [Extended Thinking](/features/ai/extended-thinking)

***

### `--1m` / `--no-1m`

**Scope:** All profiles
**Purpose:** Enable/disable 1M token extended context window
**Priority:** MEDIUM

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

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

```bash theme={null}
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`, `iflow`, `kiro`, `claude`, `kimi`, `cursor`, `gitlab`, `codebuddy`, `kilo`, `qoder`) plus deprecated `ghcp` compatibility
**Purpose:** Override CLIProxy backend selection
**Priority:** HIGH

```bash theme={null}
ccs codex --backend=original   # Use CLIProxyAPI
ccs kiro --backend=plus        # Required for plus-only providers
```

**Behavior:**

* Overrides `config.cliproxy.backend` setting
* Values: `original` | `plus`
* **Plus required** for `kiro`, `cursor`, `gitlab`, `codebuddy`, `kilo`, `qoder`, and deprecated `ghcp` compatibility
* Backend-specific binaries auto-downloaded if needed
* Generated local CLIProxy config selects the matching embedded CPAMC dashboard
  repository for the chosen backend

**Use Cases:**

* Test different backends without changing config
* Force specific backend for troubleshooting
* Ensure plus-only provider compatibility

**Related:** `config.cliproxy.backend`, provider compatibility

***

### `--import` (Kiro only)

**Scope:** Kiro provider
**Purpose:** Import OAuth token from Kiro IDE
**Priority:** HIGH

```bash theme={null}
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`, `qoder`)
**Purpose:** Launch interactive model configuration UI
**Priority:** MEDIUM

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

***

### `--gitlab-token-login` / `--token-login` (GitLab only)

**Scope:** GitLab Duo provider
**Purpose:** Authenticate with a GitLab Personal Access Token instead of browser OAuth
**Priority:** HIGH

```bash theme={null}
ccs gitlab --auth --gitlab-token-login
ccs gitlab --auth --token-login   # legacy alias
```

**Behavior:**

* switches GitLab auth into PAT mode
* bypasses the normal browser OAuth path
* useful for self-hosted or automation-heavy GitLab setups

**Related:** `--gitlab-url`, `--auth`

***

### `--gitlab-url <url>` (GitLab only)

**Scope:** GitLab Duo provider
**Purpose:** Use a custom GitLab base URL during auth
**Priority:** HIGH

```bash theme={null}
ccs gitlab --auth --gitlab-url https://gitlab.example.com
```

**Behavior:**

* targets self-hosted GitLab instead of `gitlab.com`
* works with browser OAuth or PAT login
* CCS switches to paste-callback mode when the custom OAuth flow cannot rely on the normal local callback path

**Related:** `--gitlab-token-login`, `--auth`, `--paste-callback`

***

### `--no-incognito` (Kiro only)

**Scope:** Kiro provider
**Purpose:** Use normal browser mode instead of incognito
**Priority:** MEDIUM

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

```bash theme={null}
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](/features/ai/glmt-controls)

***

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

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

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

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

***

### `--paste-callback`

**Scope:** OAuth providers
**Purpose:** Show auth URL and prompt for callback URL paste instead of auto-redirect
**Priority:** LOW

```bash theme={null}
ccs codex --auth --paste-callback
ccs kiro --auth --paste-callback
```

**Behavior:**

* Displays OAuth URL in terminal
* Waits for user to paste the full callback URL after completing auth in browser
* Useful when CCS cannot receive the OAuth redirect directly (e.g., reverse proxy setups)
* Alternative to `--headless` for environments where callback interception is blocked

**Related:** `--headless`, `--auth`

***

### `--port-forward`

**Scope:** OAuth providers
**Purpose:** Force port-forwarding mode for OAuth callback
**Priority:** LOW

```bash theme={null}
ccs codex --auth --port-forward
```

**Behavior:**

* Forces CCS to use port-forwarding for the OAuth callback listener
* Required in some container or remote environment setups where direct port binding fails
* CCS listens on a forwarded port instead of a standard local port

**Related:** `--headless`, `--paste-callback`

***

### `--accept-agr-risk`

**Scope:** Antigravity (agy) provider
**Purpose:** Bypass Antigravity confirmation prompt
**Priority:** MEDIUM

```bash theme={null}
ccs agy --accept-agr-risk "your prompt"
```

**Behavior:**

* Skips the one-time risk acknowledgment prompt for Antigravity provider
* Stores acceptance in config so subsequent runs do not prompt again
* Use in automation/CI where interactive prompts are not acceptable

**Related:** Antigravity provider docs, `ccs agy`

***

### `--kiro-auth-method <method>`

**Scope:** Kiro provider
**Purpose:** Select Kiro authentication method
**Priority:** HIGH

```bash theme={null}
ccs kiro --kiro-auth-method aws          # AWS device code (default)
ccs kiro --kiro-auth-method aws-authcode # AWS authorization code flow
ccs kiro --kiro-auth-method google       # Google OAuth
ccs kiro --kiro-auth-method idc          # IAM Identity Center
```

**Values:**

| Method         | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| `aws`          | AWS device code flow (default, recommended)                  |
| `aws-authcode` | AWS authorization code flow                                  |
| `google`       | Google OAuth                                                 |
| `idc`          | IAM Identity Center flow; requires `--kiro-idc-start-url`    |
| `github`       | Dashboard-only management flow, not a direct CLI launch path |

**Behavior:**

* Selects which identity provider to use for Kiro authentication
* AWS device code (`aws`) is recommended for most setups
* `idc` requires a start URL and optionally accepts region and flow overrides
* Callback-based methods pair well with `--paste-callback`

**Related:** `--auth`, `--import`, `--incognito`, `--no-incognito`

***

### `--kiro-idc-start-url <url>`

**Scope:** Kiro provider
**Purpose:** Required start URL for Kiro IDC authentication
**Priority:** HIGH

```bash theme={null}
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start
```

**Behavior:**

* Required whenever `--kiro-auth-method idc` is used
* Points CCS at the correct AWS Identity Center tenant

**Related:** `--kiro-auth-method`, `--kiro-idc-region`, `--kiro-idc-flow`

***

### `--kiro-idc-region <region>`

**Scope:** Kiro provider
**Purpose:** Optional region override for Kiro IDC
**Priority:** MEDIUM

```bash theme={null}
ccs kiro --auth --kiro-auth-method idc \
  --kiro-idc-start-url https://d-xxx.awsapps.com/start \
  --kiro-idc-region us-east-1
```

**Behavior:**

* Overrides the default region inferred by the upstream flow
* Only valid with `--kiro-auth-method idc`

**Related:** `--kiro-auth-method`, `--kiro-idc-start-url`

***

### `--kiro-idc-flow <authcode|device>`

**Scope:** Kiro provider
**Purpose:** Choose IDC auth-code vs device-code flow
**Priority:** MEDIUM

```bash theme={null}
ccs kiro --auth --kiro-auth-method idc \
  --kiro-idc-start-url https://d-xxx.awsapps.com/start \
  --kiro-idc-flow device
```

**Behavior:**

* Defaults to `authcode`
* Use `device` only when you explicitly need the device-code variant

**Related:** `--kiro-auth-method`, `--kiro-idc-start-url`

***

## Flag Combinations

Common flag combinations for typical workflows.

### Multi-Account Workflow

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

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

```bash theme={null}
# Kiro with token import and persistent browser
ccs kiro --import --no-incognito

# Kiro IDC auth with explicit start URL
ccs kiro --auth --kiro-auth-method idc --kiro-idc-start-url https://d-xxx.awsapps.com/start

# Codex with model configuration
ccs codex --config
```

### Diagnostic & Persist Workflows

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

| Flag                         | Environment Variable                               | Config Key                          |
| ---------------------------- | -------------------------------------------------- | ----------------------------------- |
| `--proxy-host`               | `CCS_PROXY_HOST`                                   | `cliproxy_server.remote.host`       |
| `--proxy-port`               | `CCS_PROXY_PORT`                                   | `cliproxy_server.remote.port`       |
| `--proxy-auth-token`         | `CCS_PROXY_AUTH_TOKEN`                             | `cliproxy_server.remote.auth_token` |
| `--proxy-protocol`           | `CCS_PROXY_PROTOCOL`                               | `cliproxy_server.remote.protocol`   |
| `--proxy-timeout`            | `CCS_PROXY_TIMEOUT`                                | `cliproxy_server.remote.timeout`    |
| `--allow-self-signed`        | `CCS_ALLOW_SELF_SIGNED`                            | N/A                                 |
| `--browser` / `--no-browser` | N/A                                                | `browser.<lane>.policy`             |
| `--no-incognito`             | N/A                                                | `cliproxy.kiro_no_incognito`        |
| `--target droid`             | `CCS_DROID_ALIASES` (argv0) / `CCS_DROID_PATH`     | `profiles.<name>.target`            |
| `--target codex`             | `CCS_TARGET_ALIASES` / `CCS_CODEX_ALIASES` (argv0) | `profiles.<name>.target`            |
| `--thinking`                 | `CCS_THINKING`                                     | `thinking.override`                 |
| `--accept-agr-risk`          | N/A                                                | N/A (stored in session)             |
| `--kiro-auth-method`         | N/A                                                | `cliproxy.kiro_auth_method`         |

**Priority:** CLI flags override environment variables override config file

### Droid/Target Environment Variables

| Variable             | Description                                                 |
| -------------------- | ----------------------------------------------------------- |
| `CCS_DROID_ALIASES`  | Comma-separated argv0 binary names that map to droid target |
| `CCS_DROID_PATH`     | Explicit absolute path to the droid binary                  |
| `CCS_TARGET_ALIASES` | Unified alias map (e.g., `codex=mycodex`)                   |
| `CCS_CODEX_ALIASES`  | Legacy comma-separated binary names for codex target        |

### Thinking Environment Variable

| Variable       | Accepted Values                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `CCS_THINKING` | `minimal`, `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

***

## Related Resources

* [CLI Commands Reference](/reference/cli-commands)
* [Configuration Schema](/reference/config-schema)
* [Error Codes](/reference/error-codes)
* [Troubleshooting Guide](/reference/troubleshooting)