Skip to main content

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.

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

pnpm i -g @chatblocks/cli
Verify: 
chatblocks --version
chatblocks-mcp --help
Node 20+ is required.

​
Log in

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. 
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: 
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: 
{
  "apiKey": "cb_live_...",
  "baseUrl": "https://chatblocks.ai/api/mcp/v1"
}
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.

​
Verify

chatblocks whoami
Prints the workspace name, plan, the first 12 chars of the key, and the resolved base URL. 
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: 
{
  "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.
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.

​
Update

The CLI is a regular npm package. To update: 
pnpm up -g @chatblocks/cli
Or whichever global-update incantation your package manager uses.

​
What’s next

Commands

Full command reference — blocks, canvases, data sources, schedule, auth.

MCP setup

The hosted MCP endpoint behind everything in the CLI.