claude-credentials-manager

KO | EN

gitlite — search

#python #hacktoberfest #typescript #golang #machine-learning #deep-learning #linux #docker #nodejs #java #awesome #awesome-list #ios #open-source

claude-credentials-manager

(★ 15)

Manage multiple Claude credentials

claude-credentials-manager Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# ccm — Claude Credentials Manager

A single-binary Go CLI for managing multiple Claude OAuth sessions locally. Switch between accounts for Claude Code, share a credential with another machine over a Cloudflare Quick Tunnel without ever copying the token, or launch `claude` against a specific credential without touching the active one.

## Install

### npm

```bash
npm install -g ccm-go
```

### Homebrew (macOS / Linux)

```bash
brew install hbinhng/tap/ccm
```

Installs the `ccm` binary and the `man ccm` manual page.

### Windows (PowerShell)

```powershell
iwr https://raw.githubusercontent.com/hbinhng/claude-credentials-manager/main/scripts/install.ps1 | iex
```

Downloads the latest release for your CPU (amd64 / arm64) into `%LOCALAPPDATA%\Programs\ccm\ccm.exe` and adds that directory to your user PATH. No admin / elevation required. Open a new terminal once the script finishes so `ccm` is on `$env:Path`.

Pin a specific version or override the install directory by downloading the script and passing flags:

```powershell
.\install.ps1 -Version v1.21.1 -InstallDir 'C:\tools\ccm'
```

### Download binary

Grab the latest release for your platform from [Releases](https://github.com/hbinhng/claude-credentials-manager/releases), then:

```bash
chmod +x ccm-*        # Linux / macOS
sudo mv ccm-* /usr/local/bin/ccm
```

### Build from source

```bash
git clone https://github.com/hbinhng/claude-credentials-manager.git
cd claude-credentials-manager
make
```

`make` bakes version/commit/build-date into the binary. A plain `go build` produces a `dev/unknown` build, which signals an untagged local build via `ccm version`.

### Shell completion

```bash
# bash
eval "$(ccm completion bash)"

# zsh
eval "$(ccm completion zsh)"

# fish
ccm completion fish | source

# powershell
ccm completion powershell | Out-String | Invoke-Expression
```

Credential `<id-or-name>` arguments are completed against the stored credentials.

## Commands

### `ccm login`

Authenticate a new Claude account via OAuth (PKCE copy-code flow). Opens your browser, you paste the code back. The new credential is auto-named after the account email (fetched from the profile endpoint); rename it later with `ccm rename` for a shorter handle.

### `ccm backup`

Import an existing unmanaged `~/.claude/.credentials.json` into the ccm store. Safe to run repeatedly — if the file is already managed by ccm, it no-ops with a warning. The imported credential is **not** activated; run `ccm use` to switch to it.

### `ccm status`

List all credentials with status, tier, expiry, and live quota.

```
$ ccm status
ID        NAME      TIER            STATUS  EXPIRES   ACTIVE
a1b2c3d4  personal  Claude Max 20x  valid   in 4 hrs  *
                                            5h: 75% (resets in 2h41m)
                                            7d: 60% (resets in 5d3h)
e5f6a7b8  work      Claude Pro      expired 2 hrs ago
```

Flags:

- `--no-quota` — skip the live quota API call (faster, offline-safe).
- `-o, --output table|json` — pick the output format. `-o json` emits a stable, versioned, minified envelope suitable for scripting.

```bash
# find the currently active credential from a script
ccm status -o json | jq '.credentials[] | select(.active)'
```

The two flags are orthogonal. See `man ccm` for the full JSON schema and field contracts.

### `ccm use <id-or-name>`

Activate a credential for Claude Code. On first use, the original `~/.claude/.credentials.json` is backed up to `~/.claude/bk.credentials.json`. If the token is expired, prompts to refresh before activation.

### `ccm refresh [id-or-name]`

Refresh the OAuth token for a credential. Pass `-a` / `--all` to refresh every stored credential concurrently. If the refreshed credential is currently active, the active credential file is updated as well.

### `ccm rename <id-or-name> <new-name>`

Give a credential a friendly name (1–32 characters, alphanumerics / hyphens / underscores, unique across the store).

### `ccm logout <id-or-name>`

Remove a credential. Pass `-f` / `--force` to skip confirmation when removing the currently active credential.

### `ccm restore`

Undo `ccm use` — remove the symlink (or managed copy on Windows) and restore the original `~/.claude/.credentials.json` from backup.

### `ccm share <id-or-name>`

Expose a credential over a Cloudflare Quick Tunnel so a remote Claude Code install can use it **without the credential ever leaving this machine**. The command runs a local reverse proxy, captures the local install's identity headers with a one-shot `claude -p`, and transitions into serving mode behind a random access token.

```
$ ccm share work
Share session for work (4300c4bc) is live.
  tunnel:  https://<random>.trycloudflare.com
Ticket (give this to the remote side):
  <base64 ticket>
```

On the remote machine, run `ccm launch --via <ticket>` (below). The proxy strips the remote side's keychain `Authorization` header and injects the target credential's real bearer on every forwarded request. Session stays alive until Ctrl-C.

With a load-balance pool, add `--sticky` to pin each Claude Code session
(identified by its `X-Claude-Code-Session-Id`) to one credential for the
life of the conversation, instead of rotating the whole pool on the
`--rebalance-interval` timer. This preserves Anthropic's prompt cache for
long sessions — a conversation keeps its warm cache on one account rather
than going cold each time the pool rotates. New sessions are pinned to the
best-feasibility credential at first contact, so load spreads organically
as each credential's quota is consumed.

A session is re-pinned only when its credential can no longer serve it: a
`401` (dead token) or a quota-exhausted `429` moves it immediately, while a
transient rate-limit `429` or a `5xx` keeps the pin so a brief blip doesn't
discard the cache. If failures persist with no successful response for ~1
hour (by which point the prompt cache has expired anyway), the pin is
released and the session re-selects. `--sticky` requires `--load-balance`.

A credential whose OAuth refresh token has been revoked or expired (the token
endpoint returns `invalid_grant`) is dropped from the pool the moment a request
hits it: the sticky session re-pins to a healthy credential, a load-balance pool
rotates to one, and a single-credential session returns a `502` telling you to run
`ccm login`. New sessions are only ever provisioned to a credential with a clean
recent record, so a failing account stops receiving new sessions immediately.

```bash
ccm share --load-balance work personal --sticky
```

For a LAN-reachable setup that skips the Cloudflare round-trip (typical case: a container on the same host):

```bash
ccm share work --bind-host host.docker.internal --bind-port 8787
```

The listener is bound to the TCP wildcard address and `--bind-host` is placed verbatim into the ticket as the dial target. No tunnel, no `cloudflared` download — but the ticket carries `http://`, so **only use this on a trusted LAN**.

Requires `claude` on `$PATH` for the capture step. If `cloudflared` isn't installed, a pinned version is downloaded to `~/.ccm/bin/` on first use (not needed with `--bind-host`).

### `ccm launch {<id-or-name> | --via <ticket>} [-- claude args...]`

Run Claude Code against a specific credential without mutating `~/.claude/.credentials.json`. Two modes.

**Local mode** — use a stored credential via a loopback passthrough proxy:

```bash
ccm launch work -- -p 'hi'
```

The proxy refreshes the token up front if it's expired or expiring soon, then execs `claude` with `ANTHROPIC_BASE_URL` pointing at itself. Lets you run multiple `claude` sessions against different ccm-managed credentials simultaneously without calling `ccm use`. Requires `ccm use` to have been run at least once previously (the child `claude` still reads its keychain bearer; the proxy overwrites it in flight).

**Remote mode** — decode a ticket from `ccm share` and launch against the remote proxy:

```bash
ccm launch --via <ticket> -- -p 'hi'
```

Does not require any ccm-managed credential on the local machine — the bearer comes from the ticket.

In both modes, any arguments after `--` are passed to `claude` verbatim.

### `ccm alias --as <name> <ccm launch args...>`

Install a persistent shell alias bound to a captured `ccm launch` invocation, so a long load-balance pool or remote ticket becomes a one-word command.

```bash
ccm alias --as cld --load-balance work personal
cld -- -p 'hi'
```

`cld` expands to `ccm launch --load-balance work personal "$@"` (or the shell-specific equivalent). Any args you pass to `cld` are appended at the end — typically the `--` separator and claude flags.

Supported shells: bash, zsh, fish, PowerShell. On hosts with multiple shells installed, `ccm alias` shows an interactive picker (or use `--shells bash,zsh` to select non-interactively). Files written: `$CCM_HOME/aliases.{sh,fish,ps1}` plus a one-time sentinel-fenced `source`/`.` snippet in each chosen shell's rc file.

```bash
ccm alias --list           # show installed aliases
ccm alias --remove cld     # delete one
```

No `--` separator is required between `ccm alias`'s own flags and the captured `ccm launch` payload. A literal `--` inside the payload is preserved verbatim (it's how `ccm launch` separates its flags from claude's). Run `ccm alias --help` for the full surface (`--force`, the macOS bash quirk, `CCM_HOME` interaction).

### `ccm ticket`

Build a `ccm launch --via` ticket from an endpoint URL and access token. Offline utility — no credential store, no network, no proxy. Useful when you already have a tunnel and bearer in hand (terminated `ccm share`, hand-rolled `cloudflared`, dev proxy) and just need the encoded form.

```bash
ccm ticket --from-endpoint https://abc.trycloudflare.com \
           --from-access-token <token>
```

Both flags required. The endpoint must be a full URL with `http`/`https` scheme and host only — no path, query, fragment, or userinfo. The token must consist only of unreserved URL bytes (`[A-Za-z0-9._~-]`); standard base64 (`+`, `/`, `=`) is rejected because those bytes do not survive userinfo encoding losslessly.

### `ccm serve`

Run a local HTTP dashboard that manages multiple concurrent `ccm share` sessions in-process. Useful when you want to hand out tickets to several teammates (or several containers on the same host) without keeping multiple `ccm share` terminals open.

```bash
# Loopback only; no auth — the default for a local dev box
ccm serve

# LAN-reachable; auto-generates an admin token and prints it once
ccm serve --bind-host 0.0.0.0

# Stable token from env + pinned port
CCM_SERVE_TOKEN=<long-random-string> ccm serve --bind-host 0.0.0.0 --bind-port 8080
```

The dashboard is a single page — a vanilla-JS SPA, no framework — that polls a small JSON API (`GET /api/credentials`, `GET /api/credentials/:id`, `POST /api/credentials/:id`, `DELETE /api/credentials/:id`). Each credential row shows its tier and status, a **View usage** button that opens a live-quota dialog, and actions: Start tunnel, Start LAN, View ticket, or Stop. The ticket dialog offers three click-to-copy fields — endpoint, raw ticket, and the ready-to-paste `ccm launch --via '<ticket>' --` command.

`--bind-host` on `ccm serve` is a **literal** bind address (unlike `ccm share --bind-host` which is ticket metadata). Empty / `127.0.0.1` / `::1` / `localhost` select loopback-only, which skips auth entirely. Any other value binds that address and activates the admin token.

Only one `ccm serve` runs at a time (enforced via `~/.ccm/serve.pid` with stale-PID detection). Sessions live in-process and do not survive restart. The server speaks HTTP — put it behind a TLS fronting proxy if you're exposing it on an untrusted network.

### `ccm version`

Print the ccm version, short git commit, and build timestamp. Same as `ccm --version`. Release binaries built via `make dist` embed this metadata at link time; plain `go build` reports `dev/unknown` placeholders.

## Credential resolution

All commands accepting `<id-or-name>` resolve the argument in order:

1. Exact UUID match
2. Exact name match
3. UUID prefix match (minimum 4 characters); an ambiguous prefix errors out with the list of matches

## Codex upstream (single-account)

ccm v1.18+ supports using a codex (ChatGPT) credential as the upstream
for Claude Code via translation. Claude Code remains the only
downstream consumer; the proxy translates its `/v1/messages` requests
to OpenAI Responses API and reshapes the SSE response back to
Anthropic shape.

### Requirements

- A logged-in codex credential (`ccm login codex`)

### Quick start

```bash
# Launch Claude Code against a codex credential
ccm launch <codex-cred-name> --model-alias 'claude-opus-*=gpt-5-codex'

# Share a codex credential as a tunnel
ccm share <codex-cred-name> \
  --model-alias 'claude-opus-*=gpt-5-codex' \
  --max-concurrency 3
```

### --model-alias

Repeatable. Maps inbound model names (what Claude Code asks for) to
upstream model names (what codex serves). Source patterns may use `*`
as a wildcard; targets are literal. Boot-time validation rejects any
two patterns whose match-sets overlap.

```
--model-alias 'claude-opus-*=gpt-5-codex'      # all opus variants → gpt-5-codex
--model-alias 'claude-haiku-*=gpt-5-mini'      # all haiku variants → gpt-5-mini
```

A request whose model matches none of the alias rules is forwarded
with the original model name. If the upstream rejects it
(`model_not_found`), the share/launch session terminates cleanly with
a logged reason.

### Limitations

- Anthropic's `redacted_thinking` content blocks are not supported by
  codex; they are dropped on request and not emitted on response.
- Codex's prompt cache is purely prefix-based; Anthropic's per-block
  `cache_control: ephemeral` markers are dropped.
- Mixed-provider pools (claude + codex creds in one `--load-balance`
  set) are not yet supported; targeted for v1.19.

## Grok upstream (single-account)

ccm supports using a grok (xAI) credential as the upstream for Claude
Code. xAI's `/v1/messages` endpoint is already Anthropic-compatible,
so this is a near-passthrough: the proxy rewrites the request's
`model` field and swaps in the grok OAuth bearer before forwarding to
`api.x.ai`, with no request/response translation needed.

### Requirements

- A logged-in grok credential (`ccm login grok`, an OAuth subscription
  login for SuperGrok / X Premium+)

### Quick start

```bash
# Launch Claude Code against a grok credential
ccm launch <grok-cred-name>

# Share a grok credential as a tunnel
ccm share <grok-cred-name>
```

A request whose model doesn't match a `--model-alias` rule is sent as
`grok-composer-2.5-fast` by default:

```bash
--model-alias 'claude-opus-*=grok-4.5'         # opus variants → grok-4.5
```

### Limitations

- Grok credentials are single-active: there is no `ccm use` /
  `~/.grok` activation path, and they never join a `--load-balance`
  pool. They work only through `ccm serve`, `ccm share`, and
  `ccm launch`.
- `ccm status` does not fetch grok usage/quota (no xAI usage endpoint
  integration).

## Environment

- **`CCM_PROXY`** — route all outbound ccm traffic through an HTTP(S) or SOCKS5 proxy (e.g. `socks5://user:pass@proxy.example:1080`). Applies to `ccm login`, `ccm refresh`, `ccm status`, `ccm backup`, and the reverse-proxy forwarding of `ccm share` and `ccm launch`. `ccm use` is deliberately excluded — activation is local, and the opportunistic token refresh it does on expired credentials runs direct. The stdlib `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` variables are **not** consulted; only `CCM_PROXY` is respected. Does not affect `cloudflared`'s own connections — set `HTTPS_PROXY` in the shell for those.
- **`CCM_SHARE_DEBUG=1`** — log captured identity headers and forwarded upstream requests in `ccm share` to stderr.
- **`CCM_LAUNCH_DEBUG=1`** — log forwarded upstream requests in `ccm launch <id-or-name>` local mode to stderr.
- **`CCM_SERVE_TOKEN`** — stable admin token for `ccm serve` on non-loopback binds (min 16 chars). When unset, `ccm serve` auto-generates a 22-char URL-safe token and prints it once at startup. Ignored on loopback binds.

## How it works

- Credentials are stored in `~/.ccm/<uuid>.credentials.json` with permission `0600`. Each file holds the OAuth tokens, the cached subscription tier, and timestamps for a single Claude account.
- **Unix / macOS:** `~/.claude/.credentials.json` is an absolute symlink pointing directly at `~/.ccm/<uuid>.credentials.json`. No intermediate copy — Claude Code always reads whatever ccm has written through the symlink.
- **Windows:** symlinks are unreliable, so a wrapper JSON file carrying a `ccmSourceId` marker is copied to `~/.claude/.credentials.json` instead. `ccm` rewrites this copy automatically when the underlying credential changes (refresh, rename).
- The original `~/.claude/.credentials.json` is backed up to `~/.claude/bk.credentials.json` on the first `ccm use` and never overwritten; `ccm restore` puts it back.

For every command, flag, and environment variable in exhaustive detail, see `man ccm`.

## License

MIT

claude-credentials-manager

claude-credentials-manager Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

claude-credentials-manager

claude-credentials-manager Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README