Skip to main content

​
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

​
Prerequisites

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

Add Your First Account

Run authentication for the provider:
ccs gemini --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.
2

Add Additional Accounts

Use the --add flag with --auth to add another account:
ccs gemini --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.
3

List All Accounts

View registered accounts:
ccs gemini --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
4

Switch Default Account

Change which account is used by default:
ccs gemini --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.
5

Use Account for Single Session

Override default without changing config:
ccs gemini --use work@company.com "Analyze this codebase"
This session uses work@company.com, but next time defaults to configured account.
6

Set Custom Nicknames (Optional)

Make accounts easier to identify:
ccs gemini --nickname personal --use user@gmail.com
ccs gemini --nickname work --use work@company.com
Now you can reference accounts by nickname:
ccs gemini --use personal
ccs gemini --accounts
# Output: personal (user@gmail.com), work (work@company.com)
7

Logout Specific Account

Remove an account:
ccs gemini --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 gemini "Complex task"
# Error: Rate limit exceeded

# Switch to secondary
ccs gemini --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 agy --use free-tier "Test request"

# Paid tier account
ccs agy --use paid-tier "Test request"

​
Troubleshooting

​
Account Not Found

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

​
Default Account Not Set

Error: No default account configured Solution: Set default explicitly: 
ccs gemini --use your-email@example.com

​
Token Expired

CCS automatically refreshes OAuth tokens 5 minutes before expiry. If manual refresh needed: 
ccs gemini --auth --use expired-account

​
Next Steps

Token Management

Learn about token refresh, session files, and troubleshooting

Remote Proxy

Deploy CLIProxy on remote server for team sharing