shc events

stream and view system events

Reference for the events command. Source: modules/events/commands/.

Single command, two modes:

default — open an SSE connection to the daemon and pretty-print live events as they arrive.
--audit — query the tamper-evident audit chain (historical records). This absorbed the old standalone shc audit command.

The stack filter rides the global -s/--stack flag in both modes; --audit additionally honours the global -t/--tenant flag (empty = all tenants for platform admins).

Flags

Flag	Type	Mode	Help
`--audit`	`bool`	—	view the audit chain instead of streaming live events
`--type` / `-T`	`str`	stream	event types to stream, comma-separated (default `docker,audit`)
`--node`	`str`	stream	filter by node ID
`--since`	`str`	both	stream: replay from sequence id; audit: start date (`YYYY-MM-DD` or RFC 3339)
`--quiet` / `-q`	`bool`	stream	hide noisy healthcheck events
`--follow` / `-f`	`bool`	audit	poll for new records every 3s
`--until`	`str`	audit	end date
`--event`	`str`	audit	filter by event code
`--actor`	`str`	audit	filter by actor
`--limit` / `-n`	`int`	audit	maximum records to show (default 100)
`--all` / `-a`	`bool`	audit	drop the stack filter

Examples

shc events                          # live stream (docker + audit events)
shc events -T docker -q             # docker events only, no healthcheck noise
shc events --since 1042             # replay everything newer than seq 1042
shc events --audit                  # last 100 audit records, all tenants
shc -s nextcloud events --audit -f  # follow one stack's audit trail
shc events --audit --since 2026-01-01 --actor admin

Reconnect / replay (stream mode)

The CLI consumes the SSE stream at GET /api/method/shc.events.stream, which carries a monotonic per-node sequence in each frame’s id: field. When the stream drops, reconnects pass Last-Event-ID: <last seen id> and the server replays everything newer (up to 1000 frames) before switching back to live forwarding. Result: a brief network blip doesn’t leave a gap in the operator’s terminal.

Multi-node clusters: sequence is per-node. Replay covers every event the local node observed — including cross-node events forwarded via the peer-broadcast path — but not events the local node never saw. See architecture/events/event-bus.md.

Audit mode

--audit reads GET /api/resource/Audit — the append-only, hash-chained audit table the audit module persists. Records are scoped to the global -t tenant when given, otherwise all tenants (UDS callers are implicit platform admins). -o json / -o yaml render the raw record slice for scripting.