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

# Multi-Account Setup

> Set up work and personal Claude accounts with CCS

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

<Note>
  Want several Claude accounts to **auto-continue** for you when one hits its
  limit, instead of switching by hand? See [Account Pools](/features/pool). This
  page covers manual per-account management; pools add automatic failover for the
  built-in `claude` provider.
</Note>

## Prerequisites

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

<Steps>
  <Step title="Add Your First Account">
    Run authentication for the provider:

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

  <Step title="Add Additional Accounts">
    Use the `--add` flag with `--auth` to add another account:

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

  <Step title="List All Accounts">
    View registered accounts:

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

  <Step title="Switch Default Account">
    Change which account is used by default:

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

  <Step title="Use Account for Single Session">
    Override default without changing config:

    ```bash theme={null}
    ccs codex --use work@company.com "Analyze this codebase"
    ```

    This session uses `work@company.com`, but next time defaults to configured account.
  </Step>

  <Step title="Set Custom Nicknames (Optional)">
    Make accounts easier to identify:

    ```bash theme={null}
    ccs codex --nickname personal --use user@gmail.com
    ccs codex --nickname work --use work@company.com
    ```

    Now you can reference accounts by nickname:

    ```bash theme={null}
    ccs codex --use personal
    ccs codex --accounts
    # Output: personal (user@gmail.com), work (work@company.com)
    ```
  </Step>

  <Step title="Logout Specific Account">
    Remove an account:

    ```bash theme={null}
    ccs codex --logout --use work@company.com
    ```

    This:

    * Revokes OAuth token
    * Removes from `accounts.json`
    * Prompts to set new default if removing default account
  </Step>
</Steps>

## Understanding Account Storage

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

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

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

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

```bash theme={null}
# Work project
ccs codex --use work

# Personal project
ccs codex --use personal
```

### Scenario 3: Testing Different Tiers

Compare behavior across quota tiers:

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

```bash theme={null}
ccs codex --accounts
```

### Default Account Not Set

**Error:** `No default account configured`

**Solution:** Set default explicitly:

```bash theme={null}
ccs codex --use your-email@example.com
```

### Token Expired

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

```bash theme={null}
ccs codex --auth --use expired-account
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Token Management" icon="key" href="/tutorials/token-management">
    Learn about token refresh, session files, and troubleshooting
  </Card>

  <Card title="Remote Proxy" icon="server" href="/tutorials/remote-proxy-deployment">
    Deploy CLIProxy on remote server for team sharing
  </Card>
</CardGroup>