Read the audit log
Merge the operator-side and on-host JSONL logs to see every state change that yoink made, also for deploys whose containers no longer exist.
yoink history reads container labels, so a removed container has no history line. The audit log is the durable record. It has two files and one merged read path:
| Side | File | Events |
|---|---|---|
| Operator | $XDG_STATE_HOME/yoink/audit/events.jsonl (default ~/.local/state/yoink/audit/) | Fleet-wide: RunStarted, RunFinished, and validation or build failures that never reach a host. |
| Host | /var/lib/yoink/audit/events.jsonl on each managed host | Per-host, for example LockAcquired, LockReleased, ContainerStarted, ContainerCreated, and DeployFailed. |
Each line has an event_id (UUIDv7), and the merged view uses it to remove duplicates. The origin field ("operator" or "host") shows which file the line came from.
Read everything from the last week
yoink audit log
The default window is 7d and the default limit is 100 rows. The newest row comes first.
ts origin host deploy_id event details
2026-05-01T15:42:01.317Z operator — 0190f0c7-c5b1-7c98-… RunFinished up ok
2026-05-01T15:42:01.299Z host cax11.example.com 0190f0c7-c5b1-7c98-… LockReleased
2026-05-01T15:41:58.612Z host cax11.example.com 0190f0c7-c5b1-7c98-… ContainerCreated docs docs-3fdc075b tag=sha-3fdc075
2026-05-01T15:41:42.005Z host cax11.example.com 0190f0c7-c5b1-7c98-… LockAcquired
2026-05-01T15:41:42.005Z operator — 0190f0c7-c5b1-7c98-… RunStarted up services=[docs]
Each run gets one deploy_id (UUIDv7). A lexicographic sort puts the runs in the sequence of their start times.
Filter by side
yoink audit log --origin operator # only the local file
yoink audit log --origin host # only the on-host SSH fetches
To see only the events that one host recorded, use --origin host together with --host <ADDR>.
Reconstruct one run
Pass the deploy_id of the run, or a unique prefix of it:
yoink audit log --deploy-id 0190f0c7-c5b1-7c98-aa92-1d77b8e91f10
# or, since the prefix is unique:
yoink audit run 0190f0c7
The command shows every event of that run, across every host, with the newest event first.
Filter by host, service, or event type
Use --host, --service, --event, and --since. You can repeat --event.
yoink audit log --host docs.example.com
yoink audit log --service api --event ContainerCreated --event DeployFailed
yoink audit log --since 30m --format json | jq 'select(.event == "DeployFailed")'
--format json writes raw JSONL, one event per line, for jq, vector, or a different tool.
Find failed deploys
yoink audit log --event DeployFailed --since 30d
A DeployFailed event has the last 30 log lines of the failed container in log_tail. yoink removes the containers of a failed attempt, so the audit log is the only place that keeps these lines.
Retention and rotation
Each active file, on the operator side and on each host, rotates at 5 MiB. yoink renames the file to events-<UTC-timestamp>.jsonl and starts a new file. If --since is more than 24 hours, yoink audit log also reads the rotated files.
yoink enforces no retention. To remove the rotated files on the hosts that are older than a retention window, run yoink audit gc:
yoink audit gc --keep 90d # default retention
yoink audit gc --keep 30d --dry-run # preview before deleting
yoink audit gc --keep 30d --host docs.example.com
yoink audit gc removes rotated files only on the hosts, and it never changes an active file. Rotated files on the operator side stay until you remove them manually. If you have a strict retention requirement, schedule yoink audit gc from cron or from a deploy hook.
In the TUI
Run yoink tui and press a (or 7) to open the Audit pane. To open the pane directly, run yoink tui --mode audit. The pane shows the same merged view. Use these keys in the pane:
| Key | Action |
|---|---|
↑↓ / j k | Select a row. |
Enter | Open or close a detail panel below the table. The panel shows the full event_id, the deploy_id, the actor and git SHA, and the log_tail of a failed deploy. |
/ | Start a substring filter across host, event name, summary, deploy_id, and actor. Enter applies the filter. Esc cancels the edit. |
r | Fetch the log again (parallel SSH per host plus one local read for the operator log). |
Esc | The first press clears the active filter. The second press returns to the Dashboard. |
See also
- Audit event schema: every event variant, its payload, and the schema version field
v. - Audit log coverage: the operations that yoink records and the operations that it does not record.
- CLI reference:
yoink audit: every flag. - TUI reference: the keys of every pane.