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.

A scheduled run with a 15-minute cron isn’t the right shape for iterating on a prompt. Two manual paths exist for testing — both Builder-only:
  • schedule.preview — one-off run of any prompt with no saved row. Streams progress over SSE. Use this while you’re drafting.
  • Run-now — fires the saved schedule’s exact prompt once, immediately. Use this when the schedule is already saved and you want to confirm it works without waiting for the next tick.

​
schedule.preview — one-off preview

The streaming MCP tool runs a one-off preview without creating a scheduledRuns row. Args mirror schedule.set minus cronExpression: 
{
  "apiKeyId": "<byok-key-id>",
  "modelId": "claude-haiku-4-5",
  "prompt": "Update the MRR block with my current Stripe MRR.",
  "blockId": "<optional-block-id>"
}
Progress streams as Server-Sent Events:
EventPayload
text-deltaChunk of model output text (throttled to 100ms intervals)
tool-call{ toolName, args } — every time the model invokes a tool
tool-result{ toolName, result } — what came back
finish{ success, toolCallCount, errorMessage? } — the final summary
Preview tools execute normally. If the agent calls blocks.setWidgetData, widget data actually updates. Customers iterate by re-running with tweaked prompts; there’s no dry-run flag.

​
How the ephemeral key works

Preview mints a system-flagged cb_live_* key just for this invocation, uses it to call MCP, then deletes it in a finally block. If the process dies between mint and delete (extremely rare), the orphaned key sits inert with no row pointing at it — acceptable for v1. A janitor cron is deferred. The audit log records the decrypt with actor: "system:schedulePreview", so preview events are distinguishable from production scheduled runs and from MCP tool calls driven by a human agent.

​
From the CLI

The CLI wraps preview at chatblocks schedule preview: 
chatblocks schedule preview "Update the MRR block with my current Stripe MRR." \
  --byok <byok-id> \
  --model claude-haiku-4-5 \
  --block <block-id>
Progress streams to stdout with a · prefix per event. See CLI → Commands.

​
Run-now — one-off fire of a saved schedule

The list row at /settings/schedule has a small Zap icon button — visible to admins on a Builder workspace when the row’s status is active. Clicking it:
  1. Calls scheduledRuns.runNow (a Convex action).
  2. Dispatches tasks.trigger("scheduled-agent-run", { scheduledRunId }) against Trigger.dev.
  3. The standard scheduled-run pipeline runs — same BYOK decrypt, same hidden key, same MCP loop.
  4. A scheduledRunHistory row appears on the History page within ~10–30 seconds.
Same path via MCP: schedule.runNow { scheduleId }. Same path via the CLI: chatblocks schedule run <id>.
Run-now is your end-to-end check that a saved schedule actually works. Preview is your iteration loop while you’re still writing the prompt.

​
When to use which

SituationUse
Drafting a brand-new promptschedule.preview (no row, instant feedback)
Verifying a saved schedule before the next cron tickRun-now
Demoing the agent loop to a teammateschedule.preview (one call, one log)
Re-firing yesterday’s broken runRun-now

​
What’s next

Concepts

What a scheduled run actually does, end to end.

CLI → schedule

Terminal commands for preview, list, history, and run.