> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kloudlinq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install ccp and create your first profile

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:

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

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

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

  ```zsh theme={null}
  RPROMPT='%F{yellow}${CCP_ACTIVE_PROFILE:+[ccp:$CCP_ACTIVE_PROFILE]}%f'
  ```
</Tip>

## 3. Install the VS Code extension

Download the latest `.vsix` from the [GitHub Releases page](https://github.com/kloudlinq/ccp-profile-manager/releases), then install it:

```bash theme={null}
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](/ccp/authentication) for the full matrix.

<Tabs>
  <Tab title="Subscription">
    ```bash theme={null}
    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`.
  </Tab>

  <Tab title="API key">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Gateway">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Bedrock / Vertex / Foundry">
    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## 5. Switch to the profile

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

```bash theme={null}
ccp list          # * marks the active profile
ccp doctor personal
```

## 6. Launch Claude Code

With the profile active in your shell, just run:

```bash theme={null}
claude
```

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

## What's next

<CardGroup cols={2}>
  <Card title="Profiles" icon="users" href="/ccp/profiles">
    How profiles are stored and isolated on disk.
  </Card>

  <Card title="Authentication" icon="key" href="/ccp/authentication">
    Every supported auth type and its routing variables.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/ccp/cli">
    Every `ccp` command.
  </Card>

  <Card title="VS Code extension" icon="code" href="/ccp/extension">
    Command palette entries, status bar, and workspace pinning.
  </Card>
</CardGroup>