> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullfrog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Watch a PR

`pullfrog watch` streams a pull request's activity to your terminal — one structured event per new review, comment, inline review thread, PR state change, or check-suite completion. It exists so a tool or agent babysitting a PR never has to poll the GitHub API in a loop: Pullfrog already receives every relevant GitHub webhook, so it fans those events out to you the instant they fire, with sub-second latency and zero GitHub rate-limit spend.

## Usage

Run it from inside your repo:

```bash theme={null}
npx pullfrog watch --pr 42
```

Or name the repo explicitly (defaults to the current git remote):

```bash theme={null}
npx pullfrog watch owner/repo --pr 42
```

Each event is printed as a single line of JSON on stdout, so the stream is trivial to pipe into another process:

```json theme={null}
{"cursor":"1041","repo":"owner/repo","pr":42,"kind":"review","createdAt":"2026-07-09T18:22:04.311Z","data":{"action":"submitted","reviewer":"octocat","state":"changes_requested","body":"needs a test","url":"https://github.com/owner/repo/pull/42#pullrequestreview-123"}}
```

Add `--pretty` for a human-readable line instead of JSON.

## Options

| Flag               | Description                                     |
| ------------------ | ----------------------------------------------- |
| `--pr <number>`    | pull request number to watch (required)         |
| `--since <cursor>` | resume from a `cursor` emitted by a prior event |
| `--pretty`         | human-readable output instead of JSON lines     |
| `-h, --help`       | show help                                       |

## Event kinds

Every line carries a `kind`, the affected `pr`, an ISO `createdAt`, an opaque `cursor`, and a curated `data` object. The `kind` is one of:

| Kind             | Fires on                                                              |
| ---------------- | --------------------------------------------------------------------- |
| `pr`             | pull request opened / closed / synchronized / edited / labeled / etc. |
| `review`         | a review submitted, dismissed, or edited                              |
| `review_comment` | an inline review comment created, edited, or deleted                  |
| `review_thread`  | an inline review thread resolved or unresolved                        |
| `comment`        | a top-level comment on the PR                                         |
| `check`          | a check suite completed (carries `status` + `conclusion`)             |

`data` holds just enough to decide whether to react (actor, action, state, a truncated body/title, and the `html_url`); fetch full detail on demand from the `url`.

## Resuming

The stream is cursor-based. Each event carries a `cursor`; if your process restarts, pass the last one you saw as `--since <cursor>` to pick up exactly where you left off without replaying what you already handled. A fresh `watch` with no `--since` starts from now — it does not replay history.

## Authentication

`watch` authenticates with your GitHub token (from `gh auth token`) and only streams events for repositories that token can read. Make sure the [GitHub App](/github) is installed on the repo and you're signed in with the GitHub CLI:

```bash theme={null}
gh auth login
```