Multi-Account Setup

Overview

CCS supports multiple accounts per OAuth provider (Gemini, Codex, Antigravity, etc.), enabling you to:

Work around rate limits by switching accounts
Separate personal and work usage
Test with different quota tiers
Organize projects by account

Want several Claude accounts to auto-continue for you when one hits its limit, instead of switching by hand? See Account Pools. This page covers manual per-account management; pools add automatic failover for the built-in claude provider.

Prerequisites

CCS CLI installed
OAuth provider configured (gemini, codex, agy, iflow, kiro, kimi, ghcp)
Browser for OAuth flow

Add Your First Account

Run authentication for the provider:

ccs codex --auth

This opens your browser for OAuth. After authorizing, CCS stores the token and assigns a default nickname (your email).Note: First account becomes the default for that provider.

Add Additional Accounts

Use the --add flag with --auth to add another account:

ccs codex --add --auth

CCS detects this as a new account and:

Opens browser for second OAuth flow
Stores token separately from first account
Updates ~/.ccs/cliproxy/accounts.json registry

Tip: You can add unlimited accounts per provider.

List All Accounts

View registered accounts:

ccs codex --accounts

Output shows:

Account nicknames (email or custom name)
Default account marker
Last used timestamp

Example output:

[i] Gemini accounts:
  * user@gmail.com (default) - Last used: 2026-01-05
    work@company.com - Last used: 2026-01-03

Switch Default Account

Change which account is used by default:

ccs codex --use work@company.com

This updates the default in config.yaml under cliproxy.variants.gemini.account.Note: Switching only affects future sessions, not active ones.

Use Account for Single Session

Override default without changing config:

ccs codex --use work@company.com "Analyze this codebase"

This session uses work@company.com, but next time defaults to configured account.

Set Custom Nicknames (Optional)

Make accounts easier to identify:

ccs codex --nickname personal --use user@gmail.com
ccs codex --nickname work --use work@company.com

Now you can reference accounts by nickname:

ccs codex --use personal
ccs codex --accounts
# Output: personal (user@gmail.com), work (work@company.com)

Logout Specific Account

Remove an account:

ccs codex --logout --use work@company.com

This:

Revokes OAuth token
Removes from accounts.json
Prompts to set new default if removing default account

Understanding Account Storage

Registry File: `~/.ccs/cliproxy/accounts.json`

{
  "gemini": {
    "personal": {
      "email": "user@gmail.com",
      "tokenPath": "~/.ccs/cliproxy/gemini-personal.json",
      "createdAt": "2026-01-05T10:30:00Z",
      "lastUsed": "2026-01-05T14:20:00Z"
    },
    "work": {
      "email": "work@company.com",
      "tokenPath": "~/.ccs/cliproxy/gemini-work.json",
      "createdAt": "2026-01-03T09:15:00Z",
      "lastUsed": "2026-01-03T18:45:00Z"
    }
  }
}

Config Reference: `~/.ccs/config.yaml`

cliproxy:
  oauth_accounts:
    personal: user@gmail.com
    work: work@company.com
  variants:
    gemini:
      account: personal  # Default account

Common Use Cases

Scenario 1: Rate Limit Rotation

If you hit quota limits, switch to another account:

# Primary account hits limit
ccs codex "Complex task"
# Error: Rate limit exceeded

# Switch to secondary
ccs codex --use secondary "Complex task"
# Success

Scenario 2: Separate Work/Personal

Keep projects isolated:

# Work project
ccs codex --use work

# Personal project
ccs codex --use personal

Scenario 3: Testing Different Tiers

Compare behavior across quota tiers:

# Free tier account
ccs codex --use standard-tier "Test request"

# Paid tier account
ccs codex --use premium-tier "Test request"

Troubleshooting

Account Not Found

Error: Account 'xyz' not found for gemini Solution: List accounts to verify name:

ccs codex --accounts

Default Account Not Set

Error: No default account configured Solution: Set default explicitly:

ccs codex --use your-email@example.com

Token Expired

CCS automatically refreshes OAuth tokens 5 minutes before expiry. If manual refresh needed:

ccs codex --auth --use expired-account

Getting Started

Providers

Features

Tutorials

Overview

Prerequisites

Understanding Account Storage

Registry File: `~/.ccs/cliproxy/accounts.json`

Config Reference: `~/.ccs/config.yaml`

Common Use Cases

Scenario 1: Rate Limit Rotation

Scenario 2: Separate Work/Personal

Scenario 3: Testing Different Tiers

Troubleshooting

Account Not Found

Default Account Not Set

Token Expired

Next Steps

Token Management

Remote Proxy

​Overview

​Prerequisites

​Understanding Account Storage

​Registry File: ~/.ccs/cliproxy/accounts.json

​Config Reference: ~/.ccs/config.yaml

​Common Use Cases

​Scenario 1: Rate Limit Rotation

​Scenario 2: Separate Work/Personal

​Scenario 3: Testing Different Tiers

​Troubleshooting

​Account Not Found

​Default Account Not Set

​Token Expired

​Next Steps

Token Management

Remote Proxy

Overview

Prerequisites

Understanding Account Storage

Registry File: `~/.ccs/cliproxy/accounts.json`

Config Reference: `~/.ccs/config.yaml`

Common Use Cases

Scenario 1: Rate Limit Rotation

Scenario 2: Separate Work/Personal

Scenario 3: Testing Different Tiers

Troubleshooting

Account Not Found

Default Account Not Set

Token Expired

Next Steps