stackbone logs

stackbone logs targets a running agent installation. With no --agent it runs against the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. This is a stream: --json prints one envelope per log line.

Live-tail the targeted installation's logs over a server-sent stream.

Command	Purpose
stackbone logs tail	Stream log lines. Server-side filters: --run <id>, --level <info|warn|error…>, --q <text>, --trace-id <id>. Client-side: --since, --until, --limit, --follow.

The server applies --level, --q and --trace-id. The CLI applies --since and --until (a duration like 15m/2h or an ISO timestamp) and --limit (default 100) locally as lines arrive: this stream has no server-side time range or pagination. Without --follow the tail stops once --limit lines have printed; with --follow it streams until you hit Ctrl-C.

--level sets a minimum severity. The server keeps every record whose level is at or above the one you name, so --level warn keeps warn and error, while --level error keeps error alone.

logs tail does not paginate. It takes no --cursor, and no page cursor comes back, so the pagination contract the list verbs follow does not apply here. --limit caps how many lines one tail prints.

Scope the tail to a single run with --run <id> to read just that run's lifecycle: the same id you see in stackbone runs list. A failed run also carries its own error object (a message, plus a stack when the runtime captured one) on the run record, so read stackbone runs get <id> for why it failed.

Human mode prints four fields per line: the ISO timestamp, the level name, the run id (- for a line emitted outside any run), then the message.

JSON payload: one envelope per line (not a paged list). The payload is the log record itself — Pino-shaped, with the run and (inside a workflow step) the step it came from, plus a source naming where the box read it:

{
  "schema_version": 1,
  "level": 30,
  "time": 1717236000000,
  "msg": "agent booted",
  "stream": "stdout",
  "run_id": null,
  "source": { "run_id": "-", "path": "<agent:stdout>" },
}

level is the Pino number (10 trace … 60 fatal). run_id is null for a line emitted outside any run — a boot line, a lifecycle event. A line from inside a workflow step also carries trace_id (the run's trace) and step_id.

Exit codes: 0 ok (including a clean Ctrl-C stop) · 3 no project · 1 generic (e.g. invalid --limit/--since). Full table: Conventions → exit codes.