opschain events

Included from Basic tier

opschain events [flags]

Lists the targeted server's events, newest first — the estate-wide entry point of the triage flow. Every row carries its correlation id, so when no chain is known yet the flow is: opschain events --errors --since 1h, pick the row, opschain chains triage <correlation-id>.

The table is WHEN ID TYPE NODE USER CORRELATION DETAIL. ID is the event's own id — opschain events show <id> renders that one event in full, payload included; CORRELATION is the chain handle. DETAIL is whichever of the event's error, message or reason is set, flattened to one line and truncated at 72 characters unless --wide.

-o json / -o yaml emit the selected event resources verbatim.

Flags

Flag	Meaning
--errors	Only error-ish events: error: / warn: prefixes and :error / :system_error / :pre_execution suffixes. A client-side filter over the fetched page.
--since <d>	Only events newer than this duration ago (e.g. 1h, 30m). Sent to the server as a created-at bound and re-checked client-side.
--type-search <text>	Only events whose type contains this text anywhere, case-insensitively — agent finds warn:agent:halted and info:agent:request alike; a value may carry several space-separated terms, and every term (across repeats) must appear. Like --errors, a client-side filter over the fetched page (the --limit window; see the truncation note) — opschain audit --type-search is the server-side form.
--limit <n>	Server page size (default 1000, the server max). The filters apply to this one page — see the truncation note below.
--reverse	Print the same selection oldest first (latest at the bottom).
--tail <n>	Only the last N matching events, oldest first (implies --reverse).
--watch	Keep following new matching events until interrupted (Ctrl-C); with --tail N, show the last N first.
--wide	Untruncated DETAIL column.
--filter <column>[!]=<value>	Keep only rows matching the term (repeatable; terms AND). Columns are the printed table headers lowercased (spaces/dashes fold to _); * wildcards match the whole cell case-insensitively, != negates, commas mean any-of. Applied to the fetched --limit window before --tail, including each --watch batch; --errors, --type-search and --since still narrow the fetch itself. Grammar: opschain docs cli.

One server page is fetched and filtered; when the server truncated that page at the limit, the output ends with (the server page was truncated at --limit — older events were not searched) — a match older than the page is invisible, so raise --limit or tighten --since rather than trusting an empty result.

Watching

--watch polls every 2 seconds on a keyset cursor (created-at + id), so each poll prints — oldest first — exactly the matching events that landed after the previous one; nothing repeats and nothing is skipped within the page. The first Ctrl-C ends the watch cleanly with exit 0. With a machine format the stream is NDJSON (-o json) or ----separated documents (-o yaml), one per event, no table header.

Exit codes

Code	Meaning
0	Listed (an empty selection prints no matching events), or the watch was interrupted.
1	The lookup failed — e.g. events lookup answered 500 Internal Server Error.
2	Usage error, including a missing server target.

Named errors

• events need a server target — pass --server <url> or 'opschain context use <name>' (local mode has no events) — exit 2.
• --since wants a duration like 1h or 30m: <parse error> — exit 2.
• --tail wants a positive number of events — a negative N; exit 2.
• events lookup answered <status> — any answer other than 200 (or the truncated-page 206); exit 1.

Examples

The error index for the last hour:

opschain events --errors --since 1h

Follow errors live, starting from the last 10:

opschain events --errors --watch --tail 10

The most recent 20 of everything, oldest first, machine-readable:

opschain events --tail 20 -o json

See also

• opschain docs cli/chains-triage and opschain docs cli/chains-show — what to do with the CORRELATION column.
• opschain learn 5.1 — the guided events-and-chains flow.