Himansh Raj

cldz: A One-Command Launcher for Claude Code

· 3 min read

cldz: A One-Command Launcher for Claude Code

cldz is a small tool I built to solve a small but constant annoyance: running Claude Code with different credentials meant remembering and exporting the right environment variables every single time. cldz lets you pick an authentication method once, then just run cldz — it sets the variables and hands off to claude, passing through any arguments. It's MIT licensed.

npx cldzz        # first run walks you through setup, then launches Claude Code

The problem it removes

Before cldz, switching between an API key, a subscription login, and a Bedrock or Vertex setup looked like this every time:

export ANTHROPIC_API_KEY=sk-ant-...        # or
export CLAUDE_CODE_OAUTH_TOKEN=...         # or
export CLAUDE_CODE_USE_BEDROCK=1 AWS_REGION=us-east-1
claude

cldz remembers your choices in ~/.cldz/config.json and does the exporting for you. On first run it even detects credentials you already have — $ANTHROPIC_API_KEY, $CLAUDE_CODE_OAUTH_TOKEN, existing ~/.claude / ~/.codex logins — and offers to make matching profiles.

Auth methods it handles

Each profile launches one agent (Claude Code by default, or Codex) with the right variables set. The supported methods:

  • Claude subscription (your existing ~/.claude login — nothing injected)
  • API key — sets ANTHROPIC_API_KEY
  • OAuth token (Pro / Max, from claude setup-token) — sets CLAUDE_CODE_OAUTH_TOKEN
  • Custom gateway / proxy — sets ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
  • Amazon Bedrock — sets CLAUDE_CODE_USE_BEDROCK=1, AWS_REGION, AWS_PROFILE
  • Google Vertex AI — sets CLAUDE_CODE_USE_VERTEX=1 and the Vertex project vars
  • Codex / ChatGPT subscription and OpenAI API key for the Codex agent

So you can keep a subscription profile, an API-key profile, and a Codex profile side by side and switch with cldz -P <name>.

The design decisions I care about

A couple of choices that took the most thought:

  • Session isolation by default. Each profile launches claude with its own CLAUDE_CONFIG_DIR at ~/.cldz/sessions/<profile>/. This matters because if you're already logged into Claude Code normally, that stored login would otherwise override an injected token — isolation guarantees the profile's credential is the one actually used. Your main ~/.claude is never touched.
  • Secrets are opt-in. When you save them, they land in ~/.cldz/config.json with 0600 permissions. If you'd rather not, decline the prompt and cldz reads the value from the environment each run — and a matching env var always overrides the saved value at runtime.
  • Zero runtime dependencies. The CLI intentionally ships with none, so it stays a thin, trustworthy launcher rather than a heavy framework.

There's also a shared-history option (link every profile's history back to your main ~/.claude while keeping credentials isolated) and unified api profiles that can run either agent on either provider via a proxy when they don't match natively.

What I learned

  • The boring env-var problem was worth solving. The friction was tiny per run but constant, and removing it changed how often I'd bother switching accounts.
  • Isolation is a correctness feature, not just tidiness. The subtle bug — an ambient login silently winning over an injected token — is exactly the kind of thing a launcher should protect you from.

If you want to look at the code, here it is: cldz on GitHub.