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.