Skip to main content
events reads a session’s event stream: what was written, posted, started and ended in it, in id order. It lists one page, or with --follow keeps printing new events until you stop it. It only reads. It never creates a session, and it works on a session of any status, a deleted one included while its stream lasts.

Synopsis

The session argument

A session is named in one of three shapes, the workflow reference’s path form with a session last: <revision> is default or a revision id, and each part is at most 64 characters. A bare session beside no manifest, a qualified one beside -f, and a malformed path are all SESSION_REFERENCE_INVALID, refused before any request. A session that is absent or not reachable with the key is SESSION_NOT_ACCESSIBLE; the command never creates one. The revision is read, not written, so a commit-phase revision works.

Listing

Without --follow, events sends one list_session_events request and prints the page in id order:
  • Without --after it prints the newest --limit events that match.
  • With --after it prints the oldest --limit events after that point.
--after takes an event id, a bare boundary (sixteen hex digits and a dash), or an ISO 8601 time, which is read as UTC when it has no zone and turned into the boundary id of that instant. Anything else is EVENT_FILTER_INVALID.
A line is the event’s created_at, its type, its subject and who caused it. The subject is the object alias (with the item’s type for a thread item), the execution id (with its status for execution.ended), or the session’s status. Who is the source’s kind, then the listener’s alias for a listener’s effect, the execution id for a run’s write, or the user id for an api write, and client=<tag> when the source carries one. -v appends the event id. Under --json the payload carries session, events and cursor, alongside the envelope’s schema_version:

The filter flags

--types, --aliases and --executions build the types, aliases and executions clauses of the event filter, and every clause present must hold. --listener adds a where clause on source.listener.alias, or on source.listener.definition_id when the value is a canonical id, so it selects the runs a listener started, their lifecycle events and every write they made. The filter is checked in the CLI against the platform’s grammar and bounds before anything is sent, and a breach is EVENT_FILTER_INVALID naming the clause, as the platform words it. There is no flag for where or for a raw filter.

Continuing a listing

A listing prints more: --cursor <token> when another page exists. The token is the CLI’s own: it wraps the platform’s cursor together with the direction and the filter the page was read under, because the platform’s cursor holds neither. Pass it alone:
--cursor beside --after, a filter flag or --follow is EVENT_CURSOR_INVALID, and so is a token this command did not print. --limit may change between pages.

Following

--follow polls every two seconds until you interrupt it. It does not open a WebSocket.
  • Without --after, the first pass prints the newest --limit matches, then everything new.
  • With --after, nothing is printed up front: it prints everything after that point, then everything new.
  • A late commit is not missed. An event can become visible up to 60 seconds after the time in its id, so each pass re-reads about the last minute and drops what it already printed. An event that lands late is printed once, after events with larger ids. See Settle time.
  • A quiet filter stays cheap. Each pass re-reads about the last 60 seconds of the stream, not an ever-growing window.
  • The command resolves the session once and follows it by id, so the stream of a session deleted mid-follow is still read.
It ends with exit 0 on Ctrl-C, even with a request in flight, and after printing a session.deleted event. A filter that hides session.deleted does not hide the end: the follow notices it and stops. A session that stops resolving mid-follow is SESSION_NOT_ACCESSIBLE. Each event is flushed as it is printed, so it reaches a pipe at once:
Under --json, --follow writes JSON Lines: one {"event": {...}, "schema_version": ...} object per event, and no final object, because a follow has no end to put one at. The CLI sends no client tag on its own writes, so the events it causes carry none.

Errors

Every code above, with its remediation, is in Error codes.

See also