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

# Install the CLI

> Install @chatblocks/cli for terminal access and an stdio MCP proxy.

The CLI ships as a single npm package, `@chatblocks/cli`. It includes two binaries:

* **`chatblocks`** — terminal CLI for common operations (list / get / create on blocks, canvases, data sources, schedules).
* **`chatblocks-mcp`** — stdio MCP server that proxies to the hosted `/api/mcp/v1` endpoint. Use it from any MCP client that only speaks stdio (Claude Desktop, some IDE plugins).

Both binaries are HTTPS clients against the hosted MCP server. There's no Convex dep, no internal SDK — just a pure JSON-RPC client.

## Install

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm i -g @chatblocks/cli
  ```

  ```bash npm theme={null}
  npm i -g @chatblocks/cli
  ```

  ```bash bun theme={null}
  bun add -g @chatblocks/cli
  ```

  ```bash yarn theme={null}
  yarn global add @chatblocks/cli
  ```
</CodeGroup>

Verify:

```bash theme={null}
chatblocks --version
chatblocks-mcp --help
```

Node 20+ is required.

## Log in

```bash theme={null}
chatblocks login
```

You'll be prompted for an API key and (optionally) a base URL. The CLI validates the key by calling `workspace.get` against the MCP endpoint before saving — if your key is wrong, you'll know immediately.

```text theme={null}
API key (cb_live_...): cb_live_...
Base URL [https://chatblocks.ai/api/mcp/v1]:
Logged in to workspace: My Workspace (builder)
```

You can also pass flags non-interactively:

```bash theme={null}
chatblocks login --api-key cb_live_... --base-url https://chatblocks.ai/api/mcp/v1
```

Config is written to `~/.chatblocks/config.json` with file mode `0600`. Fields:

```json theme={null}
{
  "apiKey": "cb_live_...",
  "baseUrl": "https://chatblocks.ai/api/mcp/v1"
}
```

<Tip>
  Need to point at a non-default endpoint (e.g. a Convex dev deploy)? Set `CHATBLOCKS_BASE_URL` in your shell. It overrides the stored `baseUrl` per invocation — handy for testing without re-running `login`.
</Tip>

## Verify

```bash theme={null}
chatblocks whoami
```

Prints the workspace name, plan, the first 12 chars of the key, and the resolved base URL.

```bash theme={null}
chatblocks logout
```

Removes `~/.chatblocks/config.json`.

## Use `chatblocks-mcp` from Claude Desktop

Claude Desktop only speaks stdio, so use the proxy. After `chatblocks login` succeeds, add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the Windows equivalent:

```json theme={null}
{
  "mcpServers": {
    "chatblocks": {
      "command": "chatblocks-mcp"
    }
  }
}
```

Restart Claude Desktop. The proxy reads the same `~/.chatblocks/config.json` the CLI uses, forwards `tools/list` and `tools/call` over HTTPS, and pipes the result back to stdio.

<Warning>
  Streaming tools (`blocks.create`, `blocks.build`, `dataSources.testConnection`, `dataSources.triggerRefresh`, `schedule.preview`) work through the proxy, but only the final result reaches the stdio client today — intermediate progress notifications aren't bridged. For real-time progress, use the HTTP transport directly.
</Warning>

## Update

The CLI is a regular npm package. To update:

```bash theme={null}
pnpm up -g @chatblocks/cli
```

Or whichever global-update incantation your package manager uses.

## What's next

<CardGroup cols={2}>
  <Card title="Commands" icon="terminal" href="/cli/commands">
    Full command reference — blocks, canvases, data sources, schedule, auth.
  </Card>

  <Card title="MCP setup" icon="plug" href="/mcp/setup">
    The hosted MCP endpoint behind everything in the CLI.
  </Card>
</CardGroup>