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 groups commands by resource. Run chatblocks --help to see the top-level surface, or chatblocks <group> --help to dig into one. 
chatblocks <command> [args]

Auth          login, logout, whoami
Blocks        blocks list, blocks get, blocks new
Canvases      canvases list, canvases get
Data sources  data-sources list
Schedules     schedule list, schedule history, schedule preview, schedule run
Most read commands accept --json to dump raw JSON instead of the human table. Streaming commands print progress events with a · prefix and a final summary line.

​
Auth

​
chatblocks login

Log in by pasting an API key. Validates by calling workspace.get before writing config. 
chatblocks login
chatblocks login --api-key cb_live_... --base-url https://chatblocks.ai/api/mcp/v1
Writes ~/.chatblocks/config.json with mode 0600. See Install.

​
chatblocks logout

Removes ~/.chatblocks/config.json.

​
chatblocks whoami

Prints the workspace name, plan, key prefix, and base URL. 
Workspace: My Workspace (builder)
API key:   cb_live_xxx...
Base URL:  https://chatblocks.ai/api/mcp/v1

​
Blocks

​
chatblocks blocks list

List blocks in the current workspace. 
chatblocks blocks list
chatblocks blocks list --published
chatblocks blocks list --json
Flags:
  • --published — show only published blocks.
  • --json — raw JSON output instead of a table.
Sample table: 
ID         SLUG          NAME              PUBLISHED  UPDATED_AT
blk_123    mrr           Stripe MRR        true       2026-05-19T...
blk_456    weather-sf    Weather SF        false      2026-05-19T...

​
chatblocks blocks get <id>

Print one block as JSON. 
chatblocks blocks get blk_123

​
chatblocks blocks new <prompt>

Stream a new block from a prompt. Uses the AI block generator (blocks.create) — Builder plan only. 
chatblocks blocks new "show my Stripe MRR" --slug mrr
Progress streams to stdout: 
· { type: "text-delta", textDelta: "import React from..." }
· { type: "text-delta", textDelta: "..." }

Created block blk_789 (slug: mrr).
The generated block is saved as a draft (isPublished: false). To ship it, run blocks.build then blocks.publish via your coding agent or the in-app editor.

​
Canvases

​
chatblocks canvases list

List canvases in the workspace. 
chatblocks canvases list
chatblocks canvases list --json

​
chatblocks canvases get <id>

Print one canvas as JSON. 
chatblocks canvases get cnv_abc

​
Data sources

​
chatblocks data-sources list

List data sources in the workspace. 
chatblocks data-sources list
chatblocks data-sources list --json
Sample table: 
ID         TYPE      LABEL              STATUS   LAST_REFRESH_AT
ds_111     stripe    Production Stripe  active   2026-05-19T...
ds_222     postgres  Analytics DB       active   2026-05-19T...
Create / edit / delete for data sources is not in the CLI today — use the web wizards at /settings/data-sources/new/<type> or the MCP tools (dataSources.add, dataSources.editRefreshPolicy, dataSources.delete).

​
Schedule

All schedule commands are Builder-only. Free workspaces will see PRO_REQUIRED errors from the underlying MCP tools.

​
chatblocks schedule list

chatblocks schedule list
chatblocks schedule list --json

ID         STATUS    MODEL_ID           CRON_EXPRESSION  LAST_RUN_AT
sch_aaa    active    claude-haiku-4-5   */15 * * * *     2026-05-19T...
sch_bbb    paused    gpt-5.4-mini       0 9 * * *        2026-05-18T...

​
chatblocks schedule history <id>

Show recent run history for a scheduled run. 
chatblocks schedule history sch_aaa
chatblocks schedule history sch_aaa --limit 100
chatblocks schedule history sch_aaa --json
Flags:
  • --limit <n> — number of rows to fetch (default 50, max 200).
  • --json — raw JSON.

​
chatblocks schedule preview <prompt>

Stream a one-off preview of a scheduled prompt. No row is saved; the runner mints an ephemeral key, runs the loop, and deletes the key when done. See Preview and run-now. 
chatblocks schedule preview "Update the MRR block with my current Stripe MRR." \
  --byok byok_abc \
  --model claude-haiku-4-5 \
  --block blk_123
Required flags:
  • --byok <id> — BYOK key id (find via byokKeys.list over MCP or the /settings UI).
  • --model <id> — must be in the model whitelist (claude-opus-4-7, claude-sonnet-4-6, claude-haiku-4-5, gpt-5.5, gpt-5.4-mini, gpt-5).
Optional:
  • --block <id> — focus the run on a specific block (the agent has a clearer target for blocks.setWidgetData).
Progress events stream to stdout; the final line is success/failure summary.

​
chatblocks schedule run <id>

Trigger a one-off run of an existing saved schedule. Wraps schedule.runNow. 
chatblocks schedule run sch_aaa

Triggered run rn_xyz. Check history with `chatblocks schedule history sch_aaa`.
The actual run happens on Trigger.dev’s worker; a scheduledRunHistory row appears within ~10–30 seconds.

​
Global

​
CHATBLOCKS_BASE_URL env var

Overrides the stored baseUrl per invocation. Useful for pointing at a Convex dev deploy without re-running login. 
CHATBLOCKS_BASE_URL=https://my-dev.convex.cloud/api/mcp/v1 chatblocks blocks list

​
What’s next

Install

Get the CLI on your machine and log in.

MCP tool reference

The full tool surface — every CLI command wraps one of these.