GitHub CLI's New gh event listen Command Lets Developers Wait for Pull Request Events Instead of Polling
GitHub CLI v2.105.0 adds gh event listen, a preview command built on GitHub Event Streams that waits for pull request changes instead of polling in a loop.
Overview
GitHub CLI now has a command for waiting on a pull request to change instead of checking it repeatedly in a loop. According to GitHub’s changelog, “GitHub CLI now supports GitHub Event Streams,” and with gh v2.105.0, “you and your agents can wait for a pull request to change with a single command instead of polling it in a loop.” The new gh event listen command, along with a set of gh event subscription management commands, is in preview and may change, according to the same changelog entry.
What We Know
Running gh event listen against a pull request URL “creates the subscription, opens the stream and prints each event as a line of JSON,” according to GitHub. The GitHub CLI manual specifies that each event is written to stdout as one CloudEvent JSON object per line, while status messages go to stderr, keeping stdout limited to events.
Five event types are currently supported, per the CLI manual: com.github.pull_request.review.submitted.v1 for a submitted review, com.github.pull_request.state.changed.v1 for a merge, close, reopen, ready-for-review, or draft conversion, com.github.pull_request.head.changed.v1 for a head-branch change, com.github.pull_request.merge_conflict.v1 for a detected merge conflict, and com.github.pull_request.check_suite.status.changed.v1 for a completed check suite.
By default the command exits after the first event, which GitHub says is so it “slots into scripts and agent loops,” according to the changelog. The --count flag waits for a specific number of events instead, --follow keeps listening indefinitely, and --timeout caps how long the command waits; the manual notes that the command exits with status 8 if the timeout is reached before an event arrives. The --jq and --template flags let users extract just the fields they need from each event, and gh event subscription create, list, view, and delete manage subscriptions directly rather than through listen.
The feature builds on GitHub Event Streams, which GitHub announced entered preview the day before the CLI integration shipped. Event Streams delivers events over a persistent connection rather than requiring a webhook endpoint; GitHub’s documentation states that “your client doesn’t need a public endpoint the way webhooks do,” which lets tools running on a developer’s own machine receive events without exposing anything to the internet. GitHub frames the underlying shift in broad terms: “With Event Streams, your agent sleeps while there’s no work and wakes as soon as there is,” the company wrote, adding that “GitHub is now a real-time coordination layer between developers, agents, and automation.”
Access to Event Streams is gated behind a waitlist, and both the underlying feature and the gh event commands are explicitly marked as preview and subject to change, according to GitHub. GitHub’s documentation lists several concrete limits: a maximum of 100 active subscriptions per token, one subscription per pull request, subscriptions that expire 24 hours after creation, and no replay of events that occurred before a listener attached. The CLI manual adds that events are available only for pull requests on github.com, not on GitHub Enterprise Server or GHE.com.
GitHub has also built discovery of the new command into existing CLI workflows: gh pr create, gh pr view, gh run view, gh run watch, and gh api now suggest gh event listen in place of polling, according to the changelog.
What We Don’t Know
GitHub has not said when Event Streams or gh event listen might move from preview to general availability, nor whether the 100-subscription and 24-hour limits will change before then. Coverage so far traces to GitHub’s own changelog and documentation; it is not yet clear how quickly third-party CLI scripts, CI systems, or coding-agent tooling will adopt the new command in place of existing polling loops.
Analysis
Polling a pull request for status changes is a common pattern in both human-written scripts and automated agents, and it has a known cost: checking too often burns rate-limit budget on requests that return no change, while checking too rarely delays a response to something that already happened. By moving that wait into a single CLI command backed by a persistent stream, GitHub is replacing a piece of logic that many tools previously had to build themselves — a change that, per the sources above, GitHub frames explicitly around reducing wasted requests and shortening the gap between an event happening and something reacting to it.