tail-events

Open a long-lived SSE connection for live event delivery.

Examples

# shortcut flags
pearing-cli tail-events --self
pearing-cli tail-events --repo teams/platform/website --kind pull-created
pearing-cli tail-events --self --team pearing --kind thread-created
pearing-cli tail-events --thread teams/pearing/pearing/42

# raw --scope (still supported, can be mixed with shortcuts)
pearing-cli tail-events --scope self
pearing-cli tail-events --scope repo:teams/pearing/pearing --kind pull-created
pearing-cli tail-events --scope self --last-event-id 120
pearing-cli tail-events --scope self --html

# raw SSE output (verbatim wire bytes, still reconnects)
pearing-cli tail-events --self --raw

Expected Response

Keeps one SSE request open and prints each delivered event payload as it arrives. In default mode, each payload is a JSON event object with rendered summary.web_url and summary.api_url fields. With --html, each payload is the rendered event partial HTML. With --raw, the verbatim SSE bytes are written to stdout (comments, retry hints, ids, and data lines) while reconnect and retry tracking still work normally.

The stream begins with an immediate : ok comment frame and the server's retry: hint before later event payloads arrive.

Temporary disconnects are treated as a normal reconnect path. The CLI follows the server's retry: hint and only prints errors when the stream cannot be re-established.

Reverse Proxy Note

If you run pearing behind nginx or another reverse proxy, /api/v1/tail-events must be configured as a streaming endpoint with buffering disabled.

Help Output

Tail events over SSE.

Usage: pearing-cli tail-events [OPTIONS]

Options:
      --scope <SCOPE>                Scope filter. Repeat to include multiple scopes
      --self                         Shortcut for --scope self
      --team <TEAM>                  Shortcut for --scope team:<slug>. Repeat for multiple teams
      --repo <REPO>                  Shortcut for --scope repo:<locator>. Repeat for multiple repos
      --thread <THREAD>              Shortcut for --scope thread:<locator>/<number>
      --user <USER>                  Shortcut for --scope user:<username>. Repeat for multiple users
      --kind <KIND>                  Event kind filter. Repeat to include multiple kinds
      --last-event-id <LAST_EVENT_ID>
                                     Resume from the event after this id
      --html                         Stream rendered HTML partials instead of JSON event objects
      --raw                          Write raw SSE bytes to stdout without extracting data fields
  -h, --help                         Print help