Events

Commands for listing, tailing, inspecting, and diffing recorded events. This is the per-day terminal surface — the same data the dashboard shows, but pipe-friendly.

--project is optional once es projects use <id> has been run; it falls back to the saved default.

Commands

Command	What it does
es events list [filters|--prompt|--query] [--limit N] [--all]	Page through events newest-first. With --all, follows next_cursor through every page.
es events watch [filters] [--interval 3s]	Polls and prints new events as they arrive, deduped by event ID.
es events describe <event-id> [--format yaml|json]	Full event with nested actor / target / metadata / origin / result / change decoded inline. YAML default.
es events diff <event-id>	Unified diff of change.before vs change.after. Errors clearly when the event has no change record.

Prompt

es events list --prompt "<natural language>" sends the prompt to the API's NLP endpoint, which translates it into the filter DSL, then runs the list. The translated DSL is echoed to stderr in table mode so you can see what the model produced — useful both as a sanity check and as a way to learn the DSL syntax.

es events list --prompt "show me secret rotations from this last week"

A spinner shows on stderr during translation when stderr is a TTY; piped/CI usage stays silent.

If the model can't translate a prompt into any DSL, the command errors with the model's explanation rather than silently returning every event in the project.

Query

es events list --query "<dsl>" sends a hand-written filter DSL expression directly to the API. Use this when you already know the syntax or have copied a DSL string from a previous --prompt run.

es events list --query 'action="user.login" and result.status="failure"'

--prompt and --query are mutually exclusive with each other and with the structured filter flags — mixing them is rejected client-side, since combining a translated NL prompt with hand-written filters makes the resulting query opaque.

Structured filters

Both list and watch accept these:

Flag	What it filters on
--since <when>	Lower time bound. See Time formats.
--before <when>	Upper time bound.
--action <verb>	Exact action match — e.g. --action user.login.
--actor <id>	Match on actor.id.
--actor-type <type>	Match on actor.type — e.g. --actor-type service.
--target-type <type>	Match on target.type.
--tenant <id>	Match on tenant_id.

Time formats

--since and --before accept three shapes:

Format	Example	Meaning
RFC 3339 timestamp	2026-05-09T12:00:00Z	Absolute.
Go duration	30m, 1h, 24h	This far ago.
Nd	7d, 30d	N days ago.

Diff

es events diff <event-id> renders a unified +/- diff of change.before against change.after for mutation events. The command errors clearly when the event has no change record (most events don't).

es events diff d9ce314e-996b-401f-97fc-0340c4fdb334

The diff respects redaction the same way the dashboard does — any field your recorder passed through WithRedactedFields shows as [REDACTED] on both sides. The diff command has no --format flag; the unified view is the only output.