Migration Guide: v6 → v7

Complete migration guide covering all features introduced in v6 and v7, including customizable auth, variant-specific configuration, remote CLIProxy support, new OAuth providers, and token refresh improvements.

Version Overview

Version	Release	Key Features
v7.2	2026-01	Kiro OAuth support, GHCP Device Code flow
v7.1	2025-12	Remote CLIProxy support, proactive token refresh
v6	2025-11	Customizable auth tokens, variant-specific auth, port isolation
v5	2025-10	Remote proxy configuration (deprecated in v7.1)

Breaking Changes Summary

Review all breaking changes before upgrading to v7.

v7.2 Breaking Changes

None - Fully backward compatible with v7.1

v7.1 Breaking Changes

None - Fully backward compatible with v6

v6 Breaking Changes

Config Schema:

config.json → config.yaml (automatic migration)
New required field: version: 6
cliproxy.auth structure changed (automatic migration)

CLI Flags:

--proxy-server deprecated → use --proxy-host
--proxy-auth deprecated → use --proxy-auth-token

Migration Checklist

Backup Configuration

cp ~/.ccs/config.yaml ~/.ccs/config.yaml.backup
cp ~/.ccs/cliproxy/accounts.json ~/.ccs/cliproxy/accounts.json.backup

CCS creates automatic backups, but a manual backup is recommended.

Update CCS

npm update -g @kaitranntt/ccs

# Or force reinstall
npm install -g @kaitranntt/ccs@latest

Verify Migration

ccs --version
ccs doctor
ccs doctor --fix

Test Profiles

ccs
ccs gemini --auth
ccs glm

New Features in v7.2

1. Kiro OAuth Support (HIGH PRIORITY)

What’s New:

Full OAuth support for Kiro provider (AWS Bedrock Claude)
Browser-based authentication flow
Token import from Kiro IDE

Migration Steps:

Fresh Setup
Import from IDE
Incognito Mode

# First-time Kiro setup
ccs kiro --auth

Browser opens for AWS SSO login. Authenticate and grant access.

# Import token from Kiro IDE
ccs kiro --import

Automatically imports credentials from ~/.kiro/ directory.

# config.yaml - Disable incognito for persistent AWS session
cliproxy:
  kiro_no_incognito: true

Or use the CLI flag:

ccs kiro --no-incognito

Configuration:

cliproxy:
  oauth_accounts:
    kai-work: "kai@work.com" # Kiro account
  variants:
    kiro-dev:
      provider: kiro
      account: kai-work
      settings: "~/.ccs/kiro-dev.settings.json"
  kiro_no_incognito: false # Default: false (use incognito)

CLI Flags:

Flag	Purpose
`--auth`	Authenticate via browser OAuth
`--import`	Import token from Kiro IDE
`--no-incognito`	Use normal browser mode (saves session)
`--use <account>`	Switch Kiro account
`--accounts`	List all Kiro accounts

Use Cases:

Access AWS Bedrock Claude via Kiro
Use Claude via AWS SSO with MFA
Persistent AWS session (no re-auth)

2. GHCP Device Code Flow (HIGH PRIORITY)

What’s New:

GitHub Copilot (GHCP) provider now uses Device Code flow
No headless browser required
Better support for SSH/remote environments

Migration Steps:

# Headless browser flow (deprecated)
ccs ghcp --headless
# Copy URL, open in local browser

Configuration:

cliproxy:
  oauth_accounts:
    kai-personal: "kai@github.com"
  variants:
    ghcp-work:
      provider: ghcp
      account: kai-personal

CLI Usage:

# First-time setup
ccs ghcp --auth

# Add another GitHub account
ccs ghcp --auth --add

# Switch accounts
ccs ghcp --use work-account

# List accounts
ccs ghcp --accounts

Benefits:

Works in SSH sessions
No browser automation
More reliable auth flow
Better UX for remote development

New Features in v7.1

3. Remote CLIProxy Support (HIGH PRIORITY)

What’s New:

Connect to remote CLIProxyAPI server
Share proxy across multiple machines
Fallback to local proxy if remote unreachable

Migration Steps:

Configure Remote Proxy

cliproxy_server:
  remote:
    enabled: true
    host: "proxy.example.com"
    port: 8443 # Optional (default: 443 for HTTPS, 80 for HTTP)
    protocol: "https" # http or https
    auth_token: "your-token-123"
    management_key: "mgmt-key-456" # Optional (falls back to auth_token)
    timeout: 5000 # Optional (default: 2000ms)
  fallback:
    enabled: true # Graceful degradation
  local:
    port: 8317
    auto_start: true # Auto-start local if remote fails

Test Connection

ccs gemini

This will try the remote proxy first. Check logs for connection status:

[i] Connecting to remote proxy at https://proxy.example.com:8443
[OK] Remote proxy connected

Force Remote Only

ccs gemini --remote-only

Fails with PROXY_ERROR if the remote proxy is unreachable.

CLI Flags:

Flag	Purpose	Priority
`--proxy-host <host>`	Remote proxy hostname	HIGH
`--proxy-port <port>`	Remote proxy port	HIGH
`--proxy-auth-token <token>`	Remote auth token	HIGH
`--proxy-protocol <http\|https>`	Protocol (default: http)	MEDIUM
`--local-proxy`	Force local mode	MEDIUM
`--remote-only`	Fail if remote unreachable	MEDIUM
`--proxy-timeout <ms>`	Health check timeout	LOW
`--allow-self-signed`	Accept self-signed certs	LOW

Environment Variables:

export CCS_PROXY_HOST="proxy.example.com"
export CCS_PROXY_PORT="8443"
export CCS_PROXY_AUTH_TOKEN="your-token-123"
export CCS_PROXY_PROTOCOL="https"
export CCS_PROXY_FALLBACK_ENABLED="true"
export CCS_PROXY_TIMEOUT="5000"
export CCS_ALLOW_SELF_SIGNED="false"

Use Cases:

Centralized proxy for teams
Share OAuth credentials across machines
Reduce per-machine setup
Better security (credentials on server only)

Architecture:

┌─────────────┐          ┌──────────────────┐
│ Machine A   │          │                  │
│ ccs gemini  │─────────▶│  Remote Proxy    │
└─────────────┘          │  (8443/HTTPS)    │
                         │                  │
┌─────────────┐          │  - OAuth tokens  │
│ Machine B   │─────────▶│  - Shared cache  │
│ ccs gemini  │          │  - Session mgmt  │
└─────────────┘          └──────────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  Gemini API      │
                         │  Codex API       │
                         │  Antigravity API │
                         └──────────────────┘

Security:

Use HTTPS for production
Separate management_key for admin endpoints
Rotate tokens regularly
Use firewall rules for access control

4. Proactive Token Refresh (HIGH PRIORITY)

What’s New:

Automatic token refresh 5 minutes before expiration
Prevents mid-session auth failures
Supports Gemini, Codex, Antigravity, Qwen, iFlow

Migration Steps: No action required - Automatic for all OAuth providers How It Works:

Token Expiry Check

Before each API request, CCS checks token expiration.

Proactive Refresh

If token expires in <5 minutes, refresh automatically.

Seamless Session

User experiences no interruption.

Configuration:

# No configuration needed - enabled by default
cliproxy:
  providers:
    - gemini # Auto-refresh enabled
    - codex # Auto-refresh enabled
    - agy # Auto-refresh enabled

Logging: Enable debug logs to see refresh activity:

CCS_DEBUG=1 ccs gemini
# Output:
# [i] Token expires in 4m 32s, refreshing...
# [OK] Token refreshed, new expiry: 2025-12-16T15:30:00Z

Benefits:

No mid-session auth failures
Better user experience
Reduced support tickets

New Features in v6

5. Customizable Management Key (HIGH PRIORITY)

What’s New:

Separate management_key from api_key
Enhanced security for admin endpoints
Per-variant auth override

Migration from v5:

cliproxy:
  auth: "single-key-for-all"

Configuration:

cliproxy:
  auth:
    api_key: "custom-api-key-123"
    management_secret: "custom-mgmt-secret-456"
  variants:
    my-gemini:
      provider: gemini
      auth:
        api_key: "variant-api-key"
        management_secret: "variant-mgmt-secret"

Use Cases:

Separate API vs admin credentials
Different auth per environment (dev/prod)
Enhanced security for production

6. Variant-Specific Auth (HIGH PRIORITY)

What’s New:

Per-variant auth override
Different credentials per variant
Isolate dev/prod environments

Migration Steps:

Global Auth

# Before v6 - Single auth for all variants cliproxy: auth:

"global-key" variants: gemini-dev: provider: gemini gemini-prod: provider:
gemini ```
</Tab>
<Tab title="Variant Auth">
```yaml # v6+ - Per-variant auth cliproxy: auth: api_key: "global-default"
management_secret: "global-secret" variants: gemini-dev: provider: gemini
auth: api_key: "dev-key" management_secret: "dev-secret" gemini-prod:
provider: gemini auth: api_key: "prod-key" management_secret: "prod-secret"

Use Cases:

Separate dev/prod credentials
Per-team auth keys
Testing with different API keys
Security isolation

7. Port Isolation for Variants (MEDIUM PRIORITY)

What’s New:

Assign unique ports to variants (8318-8417)
Run multiple variants concurrently
Avoid port conflicts

Migration Steps:

cliproxy:
  variants:
    gemini-dev:
      provider: gemini
      port: 8318 # NEW: Explicit port assignment
    gemini-prod:
      provider: gemini
      port: 8319 # Different port = concurrent execution
    custom-agy:
      provider: agy
      port: 8320

Port Range:

8317: Default local proxy (reserved)
8318-8417: Available for variants (100 ports)

Use Cases:

Run dev and prod simultaneously
Multi-user environments
Isolated testing

CLI Usage:

# Terminal 1
ccs gemini-dev    # Port 8318

# Terminal 2 (concurrently)
ccs gemini-prod   # Port 8319

Configuration Priority Resolution

CCS resolves configuration values in this priority order:

1. CLI Flags (highest)
   ↓
2. Environment Variables
   ↓
3. config.yaml
   ↓
4. Defaults (lowest)

Example:

ccs gemini --proxy-host proxy.example.com

Result: CLI flag overrides env var, env var overrides config file.

Multi-Account OAuth Workflow

New in v6+: Multi-account support for all OAuth providers

Add First Account

ccs gemini --auth

Browser opens for authentication. The account is saved with the email as the default nickname.

Add Second Account

ccs gemini --auth --add

Authenticate with a different account.

List Accounts

ccs gemini --accounts

Example output:

kai@personal.com (default)
kai@work.com

Switch Account

ccs gemini --use kai@work.com

Rename Account

ccs gemini --nickname work-account

After renaming, switch with:

ccs gemini --use work-account

Configuration:

cliproxy:
  oauth_accounts:
    personal: "kai@personal.com"
    work: "kai@work.com"
  variants:
    gemini-personal:
      provider: gemini
      account: personal # Use specific account
    gemini-work:
      provider: gemini
      account: work

CLI Flags:

Flag	Purpose
`--accounts`	List all accounts
`--use <account>`	Switch default account
`--auth`	Authenticate (current account)
`--auth --add`	Add new account
`--nickname <name>`	Rename current account
`--logout`	Clear tokens for current account

Troubleshooting Migration Issues

Issue: Migration Failed

Symptom
Solution

[X] CONFIG_ERROR: Failed to migrate config

# Check migration status
ccs doctor

# Manual migration
ccs migrate

# Rollback if needed
ls ~/.ccs/backup-*/
ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/

Issue: Remote Proxy Connection Failed

Symptom
Solution

[X] PROXY_ERROR: Failed to connect to remote proxy

# Test connection
curl -H "x-api-key: your-token" https://proxy.example.com:8443/health

# Check firewall/network
telnet proxy.example.com 8443

# Force local fallback
ccs gemini --local-proxy

# Debug mode
CCS_DEBUG=1 ccs gemini

Issue: Token Refresh Failed

Symptom
Solution

[X] AUTH_ERROR: Token refresh failed

# Re-authenticate
ccs gemini --logout
ccs gemini --auth

# Check token expiration
cat ~/.ccs/cliproxy/accounts.json | jq

# Enable debug logs
CCS_DEBUG=1 ccs gemini

Issue: Port Conflict

Symptom
Solution

[X] PROXY_ERROR: Port 8318 already in use

# Find process using port
lsof -i :8318    # macOS/Linux
netstat -ano | findstr :8318    # Windows

# Kill process
kill <PID>

# Or assign different port
# config.yaml:
# cliproxy.variants.my-gemini.port: 8319

Rollback Guide

If migration fails, rollback to previous version:

Stop All CCS Processes

killall ccs
killall cli-proxy-api

Restore Backup

# List backups
ls ~/.ccs/backup-*/

# Restore
ccs migrate --rollback ~/.ccs/backup-v1-2025-12-15/

Downgrade CCS

npm install -g @kaitranntt/ccs@6.5.0

Verify

ccs --version
ccs doctor

Feature Adoption Roadmap

Recommended adoption order for v6/v7 features:

Week 1: Core Migration

Update to v7.2 - Verify automatic migration - Test existing profiles - Run ccs doctor --fix

Week 2: New Providers

Set up Kiro OAuth - Migrate GHCP to Device Code flow - Test multi-account workflows

Week 3: Remote Proxy

Deploy remote CLIProxy (if team) - Configure fallback - Test connection stability

Week 4: Advanced Features

Implement port isolation - Configure variant-specific auth - Set up monitoring/analytics

Environment Variables Reference

New environment variables in v6/v7:

Variable	Version	Purpose	Priority
`CCS_PROXY_HOST`	v7.1	Remote proxy hostname	HIGH
`CCS_PROXY_PORT`	v7.1	Remote proxy port	HIGH
`CCS_PROXY_AUTH_TOKEN`	v7.1	Remote proxy auth token	HIGH
`CCS_PROXY_PROTOCOL`	v7.1	Remote proxy protocol (http/https)	MEDIUM
`CCS_PROXY_FALLBACK_ENABLED`	v7.1	Fallback to local proxy	MEDIUM
`CCS_PROXY_TIMEOUT`	v7.1	Remote health check timeout	LOW
`CCS_ALLOW_SELF_SIGNED`	v7.1	Accept self-signed certs	LOW
`CCS_UNIFIED_CONFIG`	v6	Enable unified config mode	MEDIUM
`CCS_MIGRATE`	v6	Trigger auto-migration	MEDIUM
`CCS_DEBUG`	All	Verbose logging	HIGH

API Endpoints (New in v7)

Dashboard API endpoints for remote proxy management:

CLIProxy Control

Endpoint	Method	Purpose
`/api/cliproxy/proxy-status`	GET	Get proxy status
`/api/cliproxy/proxy-start`	POST	Start proxy
`/api/cliproxy/proxy-stop`	POST	Stop proxy
`/api/cliproxy/update-check`	GET	Check for updates
`/api/cliproxy/models`	GET	List available models
`/api/cliproxy/error-logs`	GET	Get error logs

Usage Analytics

Endpoint	Method	Purpose
`/api/usage/summary`	GET	Usage summary
`/api/usage/daily`	GET	Daily breakdown
`/api/usage/hourly`	GET	Hourly breakdown
`/api/usage/models`	GET	Model distribution
`/api/usage/insights`	GET	AI insights

Related:

Next Steps

Configuration Schema

Complete config.yaml v6 reference

File Locations

Where CCS stores data

CLI Flags

All CLI flags and options

Troubleshooting

Common issues and solutions

CLI Reference

Config Reference

API Reference

Troubleshooting

Architecture

​Migration Guide: v6 → v7

​Version Overview

​Breaking Changes Summary

​v7.2 Breaking Changes

​v7.1 Breaking Changes

​v6 Breaking Changes

​Migration Checklist

​New Features in v7.2

​1. Kiro OAuth Support (HIGH PRIORITY)

​2. GHCP Device Code Flow (HIGH PRIORITY)

​New Features in v7.1

​3. Remote CLIProxy Support (HIGH PRIORITY)

​4. Proactive Token Refresh (HIGH PRIORITY)

​New Features in v6

​5. Customizable Management Key (HIGH PRIORITY)

​6. Variant-Specific Auth (HIGH PRIORITY)

​7. Port Isolation for Variants (MEDIUM PRIORITY)

​Configuration Priority Resolution

​Multi-Account OAuth Workflow

​Troubleshooting Migration Issues

​Issue: Migration Failed

​Issue: Remote Proxy Connection Failed

​Issue: Token Refresh Failed

​Issue: Port Conflict

​Rollback Guide

​Feature Adoption Roadmap

Week 1: Core Migration

Week 2: New Providers

Week 3: Remote Proxy

Week 4: Advanced Features

​Environment Variables Reference

​API Endpoints (New in v7)

​CLIProxy Control

​Usage Analytics

​Next Steps

Configuration Schema

File Locations

CLI Flags

Troubleshooting

​Related Resources

Migration Guide: v6 → v7

Version Overview

Breaking Changes Summary

v7.2 Breaking Changes

v7.1 Breaking Changes

v6 Breaking Changes

Migration Checklist

New Features in v7.2

1. Kiro OAuth Support (HIGH PRIORITY)

2. GHCP Device Code Flow (HIGH PRIORITY)

New Features in v7.1

3. Remote CLIProxy Support (HIGH PRIORITY)

4. Proactive Token Refresh (HIGH PRIORITY)

New Features in v6

5. Customizable Management Key (HIGH PRIORITY)

6. Variant-Specific Auth (HIGH PRIORITY)

7. Port Isolation for Variants (MEDIUM PRIORITY)

Configuration Priority Resolution

Multi-Account OAuth Workflow

Troubleshooting Migration Issues

Issue: Migration Failed

Issue: Remote Proxy Connection Failed

Issue: Token Refresh Failed

Issue: Port Conflict

Rollback Guide

Feature Adoption Roadmap

Environment Variables Reference

API Endpoints (New in v7)

CLIProxy Control

Usage Analytics

Next Steps

Related Resources