> ## 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. # CLI commands > Full command reference for the chatblocks terminal CLI. The CLI groups commands by resource. Run `chatblocks --help` to see the top-level surface, or `chatblocks --help` to dig into one. ```text theme={null} chatblocks [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. ```bash theme={null} 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](/cli/install#log-in). ### `chatblocks logout` Removes `~/.chatblocks/config.json`. ### `chatblocks whoami` Prints the workspace name, plan, key prefix, and base URL. ```text theme={null} 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. ```bash theme={null} 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: ```text theme={null} 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 ` Print one block as JSON. ```bash theme={null} chatblocks blocks get blk_123 ``` ### `chatblocks blocks new ` Stream a new block from a prompt. Uses the AI block generator (`blocks.create`) — **Builder plan only**. ```bash theme={null} chatblocks blocks new "show my Stripe MRR" --slug mrr ``` Progress streams to stdout: ```text theme={null} · { 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. ```bash theme={null} chatblocks canvases list chatblocks canvases list --json ``` ### `chatblocks canvases get ` Print one canvas as JSON. ```bash theme={null} chatblocks canvases get cnv_abc ``` ## Data sources ### `chatblocks data-sources list` List data sources in the workspace. ```bash theme={null} chatblocks data-sources list chatblocks data-sources list --json ``` Sample table: ```text theme={null} 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/` 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` ```bash theme={null} chatblocks schedule list chatblocks schedule list --json ``` ```text theme={null} 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 ` Show recent run history for a scheduled run. ```bash theme={null} chatblocks schedule history sch_aaa chatblocks schedule history sch_aaa --limit 100 chatblocks schedule history sch_aaa --json ``` Flags: * `--limit ` — number of rows to fetch (default 50, max 200). * `--json` — raw JSON. ### `chatblocks schedule preview ` 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](/scheduled-runs/preview-and-run-now). ```bash theme={null} 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 ` — BYOK key id (find via `byokKeys.list` over MCP or `/settings/api-keys`). * `--model ` — 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 ` — 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 ` Trigger a one-off run of an existing saved schedule. Wraps `schedule.runNow`. ```bash theme={null} chatblocks schedule run sch_aaa ``` ```text theme={null} 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`. ```bash theme={null} CHATBLOCKS_BASE_URL=https://my-dev.convex.cloud/api/mcp/v1 chatblocks blocks list ``` ## What's next Get the CLI on your machine and log in. The full tool surface — every CLI command wraps one of these.