CLI commands

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
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...

Data sources are a Builder beta. Create / edit 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). Free workspaces can still list and delete existing sources.

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 /settings/api-keys).
--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

Auth

`chatblocks logout`

`chatblocks whoami`

Blocks

`chatblocks blocks list`

`chatblocks blocks get <id>`

`chatblocks blocks new <prompt>`

Canvases

`chatblocks canvases list`

`chatblocks canvases get <id>`

Data sources

`chatblocks data-sources list`

Schedule

`chatblocks schedule list`

`chatblocks schedule history <id>`

`chatblocks schedule preview <prompt>`

`chatblocks schedule run <id>`

Global

`CHATBLOCKS_BASE_URL` env var

What’s next

Install

MCP tool reference

​Auth

​chatblocks login

​chatblocks logout

​chatblocks whoami

​Blocks

​chatblocks blocks list

​chatblocks blocks get <id>

​chatblocks blocks new <prompt>

​Canvases

​chatblocks canvases list

​chatblocks canvases get <id>

​Data sources

​chatblocks data-sources list

​Schedule

​chatblocks schedule list

​chatblocks schedule history <id>

​chatblocks schedule preview <prompt>

​chatblocks schedule run <id>

​Global

​CHATBLOCKS_BASE_URL env var

​What’s next

Install

MCP tool reference

Auth

`chatblocks login`

`chatblocks logout`

`chatblocks whoami`

Blocks

`chatblocks blocks list`

`chatblocks blocks get <id>`

`chatblocks blocks new <prompt>`

Canvases

`chatblocks canvases list`

`chatblocks canvases get <id>`

Data sources

`chatblocks data-sources list`

Schedule

`chatblocks schedule list`

`chatblocks schedule history <id>`

`chatblocks schedule preview <prompt>`

`chatblocks schedule run <id>`

Global

`CHATBLOCKS_BASE_URL` env var

What’s next