Skip to content
SHC Docs

shc events

stream and view system events

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

Single command, two modes:

  • default: print the newest events and return. -f/--follow streams live events over SSE until interrupted instead.
  • --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 and the tenant the global -t/--tenant flag in both modes (empty = all tenants for platform admins). --actor, --until and --all filter the audit chain only and are refused without --audit.

The flags, their defaults and their help are generated from the command itself: see shc events and shc events ls. -T all reads every event class, and a class the daemon does not render is refused with X400046EVTTYP, which names the classes there are.

Terminal window
shc events # the newest 100 events
shc events -T docker -q # docker events only, no healthcheck noise
shc events -f --since 1042 # replay everything newer than seq 1042, then follow
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

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 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.