# shelbi events

Inspect the hub-global workspace-state transition log — the same feed the orchestrator reacts to.

```text
shelbi 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:

```text
<ts> task=<id> <from> -> <to> reason=<short>
<ts> worker=<name> <prev> -> <new>
<ts> project=<name> heartbeat
```

`heartbeat` 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](/docs/concepts/events-log#heartbeats) for the full
shape catalog.

Every subcommand accepts the global `-p / --project <PROJECT>` flag.

## tail

```text
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:

```bash
shelbi events tail
```

Follow the log live, the same thing the orchestrator does on bootstrap:

```bash
shelbi events tail --follow
```

Print everything from the last two hours, no live tail:

```bash
shelbi events tail --since 2h
```

Combine a longer history with a live follow:

```bash
shelbi events tail --lines 100 --follow
```

## See also

- [Events log](/docs/concepts/events-log) — the full schema of both line
  kinds and which reason tags the orchestrator recognizes.
- [Orchestrator](/docs/concepts/orchestrator) — how the scheduler turns
  events into dispatch decisions.