shelbi events
View as markdownshelbi events <SUBCOMMAND> [OPTIONS]shelbi events exposes ~/.shelbi/events.log, the append-only log of every
column transition and workspace state change across the hub. The orchestrator
follows it as its trigger stream. To see what the orchestrator is seeing, run
events tail --follow in another pane.
The most common line shapes are:
<ts> task=<id> <from> -> <to> reason=<short>
<ts> worker=<name> <prev> -> <new>
<ts> project=<name> heartbeatheartbeat is the periodic wake-up the hub poller writes when the
board is otherwise quiet. Cadence comes from the heartbeat key in
project.yaml (default 3m). See
the events log for the full
shape catalog.
Every subcommand accepts the global -p / --project <PROJECT> flag.
tail
shelbi events tail [OPTIONS]Print recent transitions, and optionally stream new ones as they're
appended. Useful for live debugging, for orchestrator bootstrap (--follow
in the background and watch with Monitor), and for post-hoc forensics
(--since 1h to scope to a window).
| Flag | Type | Default | Description |
|---|---|---|---|
-n, --lines <LINES> | integer | 20 | Number of trailing lines to print before following (or before exiting if --follow is not set). |
--since <SINCE> | duration (e.g. 10m, 2h, 1d) | — | Only show events newer than this. When set, -n is ignored and all matching lines print. |
-f, --follow | flag | off | Stream new transitions as they're appended. Exit on Ctrl-C. |
--format <FORMAT> | raw, envelope | raw | Print historical log lines, or a normalized JSON envelope with kind, project, timestamp, and the original line. Push-capable harness callbacks use this same envelope. |
Shelbi only transports events. Whether a harness wakes the orchestrator through
Claude-style Monitor output, a callback socket, or the pre-turn drain path, the
orchestrator remains responsible for deciding what action to take.
Examples
See the last twenty transitions:
shelbi events tailFollow the log live, the same thing the orchestrator does on bootstrap:
shelbi events tail --followPrint everything from the last two hours, no live tail:
shelbi events tail --since 2hCombine a longer history with a live follow:
shelbi events tail --lines 100 --followSee also
- Events log — the full schema of both line kinds and which reason tags the orchestrator recognizes.
- Orchestrator — how the scheduler turns events into dispatch decisions.