opschain audit

Included from Basic tier

opschain audit [flags]

Lists the targeted server's audit history, newest first, through the API v2 audit read (AuditService.ListAuditEntries): each event row arrives with its polymorphic source already resolved server-side in one pass — the source's kind, display name, action, node path, project and owning change or workflow run — so nothing is denormalised client-side and no v1 include= chain exists here. This verb rides the generated v2 client; it needs a PostgreSQL-backed server and answers the typed ERROR_REASON_STORE_POSTGRES_REQUIRED guidance on the embedded store.

The table is WHEN TYPE USER SOURCE NODE CORRELATION. SOURCE is the resolved context (Change Deploy web, Node staging, - when the event has no source); CORRELATION is the chain handle opschain chains triage takes.

-o json / -o yaml emit the typed entries in their protojson wire shape under entries, plus next_page_token when more remain.

Authorisation follows the v2 event posture: a principal sees only events on nodes it can read (pathless platform/login events stay visible to every authenticated principal).

Flags

Flag	Meaning
--type <t>	Only events of this exact type (repeatable; any-of).
--type-prefix <p>	Only events whose type starts with this prefix, e.g. api:changes: (repeatable; any-of with --type).
--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 in the type. Narrows --type/--type-prefix rather than widening them. Resolved server-side against the catalogue of event types and read through the exact-type index, so it stays cheap on a large history; text no event type contains lists nothing.
--username <u>	Only events recorded for this acting username.
--node-path <p>	Only events in this node path's subtree (the node and its descendants).
--system	Only system events.
--user	Only user events (mutually exclusive with --system).
--since <t>	Only events created at or after this RFC3339 instant.
--until <t>	Only events created at or before this RFC3339 instant.
--limit <n>	Entries per page (server default 50, capped at 1000).
--page-token <tok>	Continue the listing from a previous page's token.
--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 client-side within the returned page only; the dedicated flags (--type, --type-prefix, --type-search, --username, --node-path, --since, --until) narrow the search server-side. Grammar: opschain docs cli.

Pagination

The listing is cursor-paged: when more entries remain the table ends with More entries remain: continue with --page-token <tok>, and the machine formats carry the token as next_page_token. An empty token means the listing is complete.

Exit codes

Code	Meaning
0	Listed (an empty selection prints no matching audit entries).
1	The read failed — the error names the server's Connect code and message, e.g. the server answered unimplemented: this read needs the PostgreSQL store.
2	Usage error, including a missing server target or --system with --user.