Quickstart - KloudLinQ Docs

This guide walks you through installing the ccp CLI, wiring up the zsh shell integration, installing the VS Code extension, and creating your first profile.

Prerequisites

macOS (secrets are stored in the macOS Keychain)
zsh as your shell
Node.js 18+ and npm
Claude Code CLI (claude) on your PATH — required for subscription login flows
Optional: VS Code for the extension

1. Install the CLI

ccp is distributed as source. Clone the repository, build the core package, and link the CLI onto your PATH:

git clone https://github.com/kloudlinq/ccp-profile-manager.git
cd ccp-profile-manager
npm install
npm run build:core
npm link --workspace packages/core
which ccp-bin   # confirm it resolved

2. Source the zsh wrapper

ccp switch needs to mutate your current shell’s environment, and a child process can’t do that on its own — same reason nvm and pyenv ship shell functions. Source the wrapper from your ~/.zshrc:

echo 'source /absolute/path/to/ccp-profile-manager/shell/ccp-init.zsh' >> ~/.zshrc
source ~/.zshrc

Without this step, ccp switch will print an env script but won’t change the current shell.

Show the active profile in your prompt by adding this to ~/.zshrc:

RPROMPT='%F{yellow}${CCP_ACTIVE_PROFILE:+[ccp:$CCP_ACTIVE_PROFILE]}%f'

3. Install the VS Code extension

Download the latest .vsix from the GitHub Releases page, then install it:

code --install-extension ccp-profile-manager-<version>.vsix

Or build it yourself from a clone with npm run package:ext. The extension is not published to the VS Code Marketplace yet — that’s on the roadmap.

4. Create your first profile

Pick the auth type that matches your Claude Code setup. See Authentication for the full matrix.

Subscription
API key
Gateway
Bedrock / Vertex / Foundry

ccp create personal --type subscription

ccp walks you through the Claude Code OAuth browser flow and stores the resulting credentials.json inside the profile’s own CLAUDE_CONFIG_DIR.

ccp create work --type api_key

You’ll be prompted for your ANTHROPIC_API_KEY. The key goes into the macOS Keychain, never to disk in plaintext.

ccp create openrouter-play --type gateway

ccp prompts for the gateway’s base URL (for example https://openrouter.ai/api/v1) and its bearer token. The token goes into the Keychain; the base URL lives in the profile record.

ccp create work-bedrock --type bedrock
ccp create work-vertex  --type vertex
ccp create work-foundry --type foundry

These three store no local secret. They assume you’ve already authenticated with the cloud CLI on this machine (aws sso login, gcloud auth login, or az login). ccp doctor checks the session for you.

5. Switch to the profile

ccp switch personal

In a shell that has the zsh wrapper sourced, this unsets every known routing variable and applies the new profile in the current shell. CCP_ACTIVE_PROFILE is exported so you can display it in your prompt. Verify the switch:

ccp list          # * marks the active profile
ccp doctor personal

6. Launch Claude Code

With the profile active in your shell, just run:

claude

Claude Code picks up the profile’s isolated CLAUDE_CONFIG_DIR (default ~/.claude-<name>) along with the right auth variables.

What’s next

Profiles

How profiles are stored and isolated on disk.

Authentication

Every supported auth type and its routing variables.

CLI reference

Every ccp command.

VS Code extension

Command palette entries, status bar, and workspace pinning.

​Prerequisites

​1. Install the CLI

​2. Source the zsh wrapper

​3. Install the VS Code extension

​4. Create your first profile

​5. Switch to the profile

​6. Launch Claude Code

​What’s next

Profiles

Authentication

CLI reference

VS Code extension

Prerequisites

1. Install the CLI

2. Source the zsh wrapper

3. Install the VS Code extension

4. Create your first profile

5. Switch to the profile

6. Launch Claude Code

What’s next