Orchestration from the CLI
Drive runs, private tasks, workers, gates, and the coordinator inbox from the glueprint command with a scriptable JSON envelope and fixed exit codes.
- Topic
- Orchestration
- Available on
- Available onCLI Daemon
- Reviewed
- October 12, 2026
On this page
The glueprint command talks to the Glueprint runtime already running on this machine — the desktop app or the CLI daemon — and drives orchestration without a session of its own. glueprint guide orchestration prints the bundled guide for the installed version; this page is the fuller reference.
glueprint run with no subcommand still starts the daemon, exactly as before. The orchestration verbs are subcommands of run and cannot be combined with daemon options such as --port or --http-port.
Runtime discovery
Three flags are global to every command: --root <PATH>, --json, and -v / --verbose, which raises logging to debug level; for every command on this page the log goes to stderr. Every command locates the runtime through the Glueprint root: --root <PATH> first, then a nonempty GLUEPRINT_ROOT, then the default data directory. A relative root resolves from the directory you ran the command in.
From that root the CLI reads the loopback port and the operator credential the runtime wrote at startup. It connects only to the numeric loopback address, verifies GET /health and the engine identification header, and only then sends the operator bearer. The bearer never leaves the machine: a command routed to another host with --on is forwarded by the local engine under its own identity. If nothing is listening the command exits 3; if the listener is not a Glueprint engine it exits 4.
Output and exit codes
Add the global --json flag to get one compact envelope on stdout:
{"id":"<invocation uuid>","ok":true,"result":{...},"_meta":{"version":"<cli version>","host_id":"...","root":"...","elapsed_ms":42}}Failures use "ok": false and an error object with code, message, and an optional details object. Logs and wait heartbeats always go to stderr, so stdout stays parseable.
--json is accepted by status, session, host, inbox, check, the run orchestration subcommands, task, board, worker, gate, and guide. Every other command, including the daemon form of run, rejects it with exit 2 before doing anything. The older --format json on session list, session stop, and status still prints its command-specific JSON without the envelope, and in text mode session list and session stop keep their v1.3.0 error wording and exit 1, so scripts written against that version keep working.
| Exit | Meaning |
|---|---|
| 0 | The operation or observation completed. |
| 1 | A protocol, validation, conflict, storage, transport, or postcondition failure. |
| 2 | Invalid local usage: a bad flag, a nil UUID, an empty required value. |
| 3 | No local runtime is running. |
| 4 | Authentication, local authorization, or engine identification failed. |
| 5 | The local runtime answered not-found and did not mark the failure as remote (for example a run, task, gate, session, or project id that does not exist here). A missing remote host is a remote failure and exits 7. |
| 6 | The CLI deadline or a runtime request deadline expired. |
| 7 | A remote-host operation failed and the engine marked the failure as remote. |
Waiting
session and worker commands that change a session accept --wait and --timeout <SECONDS>. With --wait the CLI polls status every two seconds and returns when the session reaches ready, completed, failed, stopped, or interrupted. The default deadline is 300 seconds; --timeout without --wait only bounds the request and does not poll. Every 15 seconds a one-line JSON heartbeat goes to stderr with the last observed status. A deadline expiry exits 6 with the session id, host id, and last snapshot in details; it never stops, retries, or acknowledges anything. GLUEPRINT_CLI_POLL_INTERVAL_MS and GLUEPRINT_CLI_HEARTBEAT_INTERVAL_MS override the intervals for diagnostics, floor 100 ms.
Runs
glueprint run subcommands address the private orchestration store. A run created without --owner is operator-owned; with --owner <SESSION_UUID> the named session becomes the coordinator.
| Command | Flags | Notes |
|---|---|---|
run create | --objective <TEXT> (required), --owner <UUID>, --auto-close, --task <TITLE> (repeatable) | Initial tasks have no dependencies. Returns the run view; the id is at .result.run.id. |
run list | --owner <UUID>, --include-closed | Runs visible to the caller, with derived readiness and dispatches. |
run show <RUN_ID> | One run with tasks, derived states, dispatches, and gates. | |
run close <RUN_ID> | --reason <TEXT> | Closes as completed, failed, or cancelled from the task statuses and withdraws open gates. Does not stop live workers. |
run reset <RUN_ID> | --task <UUID> (repeatable) | Returns the selected tasks to pending, supersedes their active dispatches, withdraws their gates, and reopens the run. With no --task, every pending, dispatched, or failed task is reset. Completed and cancelled tasks cannot be reset. Does not stop live workers. |
Tasks and dependencies
Top-level glueprint task is the private store. glueprint board task ... is the product Tasks & Boards store; do not confuse the two.
| Command | Flags | Notes |
|---|---|---|
task create | --run <UUID> (required), --title <TEXT> (required), --key <TEXT>, --spec <TEXT>, --depends-on <UUID> (repeatable) | Returns the task at .result.task and its derived state at .result.state.state. |
task update <TASK_ID> | --title <TEXT>, --spec <TEXT>, --status pending|cancelled, --result <JSON> | At least one field is required. Stored status can only be set to pending or cancelled. |
task list | --run <UUID> (required), --state ready|blocked|dispatched|completed|failed|cancelled | Derived states, not stored status. |
task show <TASK_ID> | ||
task dep add <TASK_ID> | --on <UUID> (required) | Adds a dependency edge; a cycle is refused. |
task dep rm <TASK_ID> | --on <UUID> (required) | Removes the edge. |
Workers
A worker is a session started for one ready task. worker start always needs a project and carries the run and task ids; it never touches the board store.
| Command | Flags | Notes |
|---|---|---|
worker start | --run <UUID>, --task <UUID>, --agent <ID>, --project <UUID> (all required); --prompt <TEXT>, --owner <UUID>, --on <HOST_ID>, --name, --working-directory, --auto-worktree, --model, --permission-mode, --reasoning-effort, --harness-account-id, --wait, --timeout | Refused when the task is not ready or already dispatched, or the run is closed. --owner is not accepted for an operator-owned run. |
worker show <SESSION_ID> | --on <HOST_ID> | Session status plus the dispatches recorded for that child. A short id prefix is resolved locally only; with --on the full remote session UUID is required. |
worker read <SESSION_ID> | --limit <N>, --before-offset <N> | A page of the worker’s events. Local only. |
worker stop <SESSION_ID> | --on <HOST_ID>, --wait, --timeout | Stops the session. The dispatch settles from the outcome the engine records. |
worker retry <SESSION_ID> | --owner <UUID>, --stop-prior, --wait, --timeout | Starts a new attempt from a terminal or stalled prior, preserving run, task, parent, and attempt lineage. A still-live stalled prior is stopped by default; --stop-prior only sends that choice explicitly, and there is no flag to keep the prior running. If the new attempt fails to start, the error is retry_start_failed and the prior is already superseded: retry from the session in details.replacement_session_id. Local only. |
Gates
| Command | Flags | Notes |
|---|---|---|
gate create | --task <UUID> (required), --question <TEXT> (required), --option <LABEL[=VALUE]> (repeatable), --freeform, --header <TEXT>, --defer-until-dependencies-settle | Blocks the task until resolved. On a session-owned run the question also appears as a card on the coordinator session; with --defer-until-dependencies-settle the card waits until every task this task depends on has completed. |
gate resolve <GATE_ID> | --answer <TEXT> (required) | Resolves through the same path an answered question card uses. |
gate list | --run <UUID> (required), --status open|resolved|withdrawn |
An option written as Yes=yes has label Yes and value yes; Yes alone uses the label as the value. An empty value after = is a usage error.
Inbox
check reads a coordinator inbox and is shorthand for inbox check. Exactly one of --owner <SESSION_UUID> (a coordinator session) or --run <RUN_ID> (an operator-owned run) selects the inbox.
| Command | Flags | Notes |
|---|---|---|
check / inbox check | --owner or --run; --wait-ms <0..25000>; --limit <1..50> (default 50); --types <KIND,...>; --ack <RECORD_ID>... | Acknowledges the listed ids first, then returns unacknowledged records, long-polling up to --wait-ms. Kinds include task_ready, gate_resolved, worker_done, dag_stuck, stalled, and status. |
inbox ack <RECORD_ID>... | --owner or --run | Returns acked, already_acked, and unknown id lists. |
Process every record before acknowledging its exact id; unacknowledged records replay on the next read. Attempt and dispatch ids are opaque. Read a record’s attempt identity and superseded flag before deciding what a worker_done means.
Hosts and sessions
| Command | Flags | Notes |
|---|---|---|
host list | The server-authoritative host inventory: id, label, platform, online status, version, and whether the host accepts delegated workers. | |
session start | --agent <ID>, --prompt <TEXT> (required); --project <UUID> (required unless retrying); --task-id, --retry-of-session-id <UUID>, --retry-stop-prior, --owner, --on <HOST_ID>, plus the same placement flags as worker start | Starts an ordinary session. --task-id records a task attribution for delegation reporting; to dispatch against a private task use worker start. |
session send <ID> / session steer <ID> | --text <TEXT> (required), --collaboration-mode (send only), --on, --wait, --timeout | send starts the next turn of a session that is between turns. A session that is starting, running, or waiting on a prompt refuses with session_busy, and nothing is queued; steer changes a turn in flight. |
session interrupt <ID> / session status <ID> | --on, --wait, --timeout | |
session stop <ID> | --format, --offline, --on, --wait, --timeout | --offline repairs saved status when the runtime is not running; see recovery. |
session list / session events <ID> | --status, --format (list); --before-offset, --limit (events) | Local only. session list falls back to the saved session files when the runtime is not running. |
--on accepts a host id from host list. Naming the local host is the same as omitting the flag. session list, session events, worker read, and worker retry do not accept --on and exit 2 if you pass it.
A minimal round trip: run create --objective ... --task ..., then task list --run <RUN> --state ready to find the ready task id, worker start ... --wait against it, and check --run <RUN> --types worker_done,task_ready --wait-ms 25000 to collect the outcome.