> ## Documentation Index > Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt > Use this file to discover all available pages before exploring further. # aether review > Read pull request reviews and act on them from the CLI Read a pull request's review the way the web shows it (the pull request and its review runs, its review page, its stack, a file, its head snapshot, the merge box, the diff, its threads, dispatches, activity, verification and proof) and act on it: ask Aether for a review run, submit your own review, comment, reply to and resolve threads, hand feedback to the task, merge, close, reopen, draft or ready the pull request, set the proof's visibility, and request reviewers. See [Pull Request Reviews](https://docs.runaether.dev/guides/github-integration.md#pull-request-reviews) for how reviews are triggered. **Alias:** `reviews` ## Usage ```bash theme={"dark"} aether review [flags] ``` ## Naming a pull request Every `` argument takes any of: | Form | Example | | - | - | | Repository and number | `acme/web#42` | | GitHub URL | `https://github.com/acme/web/pull/42` (a trailing `/files` or `/commits` is fine) | | Aether pull request id | `5f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b` (the `pull_request_id` of `--json` output) | A repository and number is resolved to the pull request first, and the command then acts in the organization the pull request was read in. When more than one of your organizations owns a pull request, pass [`--org`](https://docs.runaether.dev/cli/overview#global-flags) to choose; without it, a pull request named by id is read in the owning organization where you hold a product role, and an ambiguous one may be refused with `org_id_required`. ## Subcommands | Subcommand | Description | | - | - | | `list` | List the organization's pull requests, reviewed or not | | `sections` | Count the organization's pull requests in each section | | `get ` | Show the pull request: state, section, verdict and review runs | | `view ` | Show the review page: description and the reviews Aether posted | | `stack ` | Show the stack the pull request belongs to | | `file --ref ` | Print one file at a commit the review read | | `snapshot ` | Show the snapshot of the pull request's head | | `snapshot retry ` | Start again a head snapshot capture that gave up | | `pr ` | Show the merge box: state, checks, GitHub reviews and reviewers | | `pr merge ` | Merge the pull request at the head you reviewed | | `pr close ` | Close the pull request without merging it | | `pr reopen ` | Reopen a closed pull request | | `pr draft ` | Convert the pull request to a draft | | `pr ready ` | Mark a draft pull request ready for review | | `diff ` | Print the changed files as a unified diff | | `thread list ` | List the review threads | | `thread reply ` | Reply to a review thread | | `thread resolve ` | Resolve the thread holding a comment | | `thread unresolve ` | Unresolve the thread holding a comment | | `dispatches ` | List the feedback dispatched to the pull request's task | | `dispatch ` | Hand review feedback to the task that fixes the pull request | | `activity ` | List the pull request's activity, newest first | | `verification ` | List the verification recorded against the pull request | | `proof ` | Show everything recorded as proof of the pull request | | `proof visibility ` | Set who may watch the proof | | `run ` | Ask Aether to review the pull request at its current head | | `submit ` | Submit your review through your GitHub identity | | `comment ` | Post a top-level comment | | `reviewer add ` | Request a review from a user or team | | `reviewer remove ` | Withdraw a user's or team's review request | With `--json`, every command prints the API's answer as is: a read prints what it read, and an action prints the object it created or changed (the pull request a `pr` subcommand or `reviewer add` changed, the thread `thread resolve` changed, the comment `comment` or `thread reply` created). `reviewer remove`, which the API answers with no body, prints the pull request and the withdrawn reviewer. ## aether review list List one page of the organization's pull requests, each with its latest review run and the section it sits in: `in_review` while its newest run reviews, `approved` when that run's standing verdict approves the current head, `other` for the rest. When more follow, the output ends with a `Next cursor:` line; pass it to `--cursor` to read the next page. Without `--view`, every pull request of a repository the organization has a project for is listed, reviewed or not, newest opened first, and only the open ones unless `--pr-state` names others. `--view reviews` keeps the pull requests the organization's review runs reviewed, newest activity first; `--view queue` keeps the open ones among them that need you first. ```bash theme={"dark"} aether review list [flags] ``` | Flag | Description | | - | - | | `--view` | `reviews` or `queue`, as above | | `--project` | Keep this project's pull requests and review runs. A default project or `AETHER_PROJECT` does not narrow the list | | `--section` | Keep one section: `in_review`, `approved` or `other` | | `--status` | Comma-joined statuses of the latest run: `reviewing`, `completed`, `failed`, `cancelled`, `superseded`, `archived`, and `unreviewed` (only without `--view`) | | `--pr-state` | Comma-joined pull request states: `open`, `closed`, `merged` | | `--viewer` | `author` keeps the pull requests you opened; `involved` adds the ones you review | | `--author` | Keep pull requests this GitHub login opened | | `--reviewer` | Keep pull requests this GitHub login reviews or was asked to review | | `--repo-owner`, `--repo-name` | Keep pull requests of matching repositories | | `--opened-after`, `--opened-before` | Keep pull requests opened in a window, as UTC instants (`2026-01-02T15:04:05Z`) | | `--updated-after`, `--updated-before` | Keep pull requests GitHub updated in a window | | `--exclude-drafts` | Leave draft pull requests out | | `--query` | A pull request number (`42` or `#42`), or words its title holds in order | | `--limit` | Pull requests per page, 1 to 100 (default 20) | | `--cursor` | Continue after a previous page, from its `Next cursor:` line | ```bash theme={"dark"} aether review list --view reviews --limit 2 ``` ``` PULL REQUEST TITLE SECTION STATE RUN VERDICT UPDATED acme/web#42 Fix the login redirect approved open #2 completed approve 5m ago acme/api#118 Page the audit log by cursor in_review open #1 reviewing - 1h ago Next cursor: eyJ2IjoxLCJzY29wZSI6... ``` With `--json`, the output is the page itself: `{"items": [...], "next_cursor": "..."}`, where each item is the pull request `aether review get` prints and `next_cursor` is `null` on the last page. ## aether review sections Count the pull requests `aether review list` lists under the same `--view` and filters, per section, before any section or cursor narrows the list. It takes the list's flags except `--section`, `--limit` and `--cursor`. An empty section is left out. ```bash theme={"dark"} aether review sections --exclude-drafts ``` ``` SECTION PULL REQUESTS in_review 1 approved 2 other 4 ``` ## aether review get Show the pull request as `aether review list` lists it: its state, head and base, section, verdict and findings, where its feedback is dispatched, where you stand on it, the organization it was read in, and its review runs, newest first. ```bash theme={"dark"} aether review get acme/web#42 ``` ## aether review view Show what the review page holds beyond the pull request: its description, the reviews Aether posted on it (newest first), how many files the reviewed head changed, its previews, and the review rounds since a human last touched it. `--json` prints each posted review's guide and inline comments. ## aether review stack Show the tree of open pull requests the pull request is stacked in, from its bottom layer up, each layer indented under the one it is based on. A stack that loops, a layer with two parents, or a stack of more than 64 pull requests in all (forks included, so a bottom layer with 64 children is already too large) is refused with `stack_cycle`, `stack_two_parents` or `stack_too_large`. ## aether review file Print one file at a commit the review read: the pull request's head or a review run's. | Flag | Description | | - | - | | `--ref` | The commit to read the file at, as its full 40-character SHA (required) | The file's text is printed as is. A path with no file at that commit, a binary file and one GitHub will not inline have no text to print, so the command fails naming the kind; `--json` prints the answer whatever its kind (`text`, `binary`, `too_large` or `not_found`). ## aether review snapshot Show the snapshot of the pull request's current head against its base: each changed file with its status and counts, and whether its content at the head is in the snapshot (`text`, `binary`, `too_large`, or `omitted` when the snapshot carries none for it). The command reads the pull request first for the head and base the snapshot describes. The first read of a head starts its capture, so a head not captured yet prints that it is capturing; read it again shortly. A capture that gave up after its retries fails with its error, and `aether review snapshot retry ` starts it again, printing the capture's state. `--json` prints the snapshot with every patch and content. ## aether review pr Show the pull request's merge box: state, author, branches, head, mergeable state, CI and checks, readiness, size, then its check runs, its GitHub reviews and its reviewers (users and teams). Its subcommands change the pull request and print the state GitHub answered with: * `aether review pr merge ` merges it with the method you name, pinned to the head you reviewed. It needs push permission on the repository, which is checked against your GitHub identity; the merge itself runs as Aether's GitHub App. * `aether review pr close ` closes it without merging it. * `aether review pr reopen ` reopens a closed pull request. * `aether review pr draft ` converts it to a draft. * `aether review pr ready ` marks a draft ready for review. `close`, `reopen`, `draft` and `ready` run through your own GitHub identity: GitHub judges your permission (a pull request's author may close it without push access), and its refusal is a 422 `validation_failed` with GitHub's message. | `merge` flag | Description | | - | - | | `--method` | `squash`, `rebase` or `merge` (required); a method the repository disallows is a 422 `validation_failed` with GitHub's message | | `--head` | The head commit you reviewed (required); a head that moved past it is refused with 409 `conflict` | | `--delete-branch` | Delete the head branch once merged, while it still points at the merged head; a fork's branch is refused with `fork_branch_delete_unsupported` | A merge GitHub refuses (conflicts, failing required checks, branch protection) is also a 409 `conflict`, with GitHub's reason, and a caller without push permission is refused with `github_push_access_required`. ```bash theme={"dark"} aether review pr merge acme/web#42 --method squash --head 3f2a9c1e5b7d4f6a8c0e2b4d6f8a0c2e4b6d8f0a --delete-branch ``` ``` Merged acme/web#42. It is merged. ``` ## aether review diff Print the pull request's changed files with their unified-diff patches, live from GitHub, in `git diff` form. A file GitHub gives no patch for (binary or oversized) prints its status and counts instead. When GitHub stops listing at its 3,000-file cap, the command fails and prints nothing rather than part of the diff; `--json` prints the files GitHub listed, with `truncated: true`. | Flag | Description | | - | - | | `--head` | The head commit the diff must describe; a head that moved past it is refused with `head_moved` | ## aether review thread Read the pull request's review threads and act on them. A thread is named by its root comment's GitHub id, the `COMMENT` column of `aether review thread list`; `WHERE` is the file, and the line on the base or the head that the thread is anchored to (a file-level thread names the file alone). ``` COMMENT WHERE STATE REPLIES AUTHOR TEXT 2154837201 src/app.ts:12 (head) open 1 aether-bot p2: this swallows the error 2154839950 src/auth.ts:40 (base) resolved, outdated 0 octocat Can this be a constant? ``` * `aether review thread reply --body ` replies through your own GitHub identity and prints the comment GitHub created. * `aether review thread resolve ` and `aether review thread unresolve ` resolve, or unresolve, the thread holding the comment through your own GitHub identity, printing the thread as GitHub left it. Resolving a resolved thread succeeds, as does unresolving an unresolved one. ## aether review dispatches List the feedback dispatched to the pull request's dispatch target, which `aether review get` names: `author_task` (the task that published it) or `review_run` (the fix-on-request review run of a pull request no task published). A pull request with no dispatch target is refused with `no_dispatch_target`. ## aether review dispatch Hand feedback on the pull request to its dispatch target, which takes review threads only when it is a review run, and print the dispatches it now holds. Pass exactly one of: | Flag | Description | | - | - | | `--thread` | The review thread holding this GitHub comment id | | `--ci` | The failing CI | | `--all` | All of the pull request's feedback | A fix request to a review run needs push permission on the repository. ## aether review activity List the pull request's history newest first: the publishing task's events, review run boundaries, delivered dispatches, GitHub review verdicts and the merge. It pages by cursor. | Flag | Description | | - | - | | `--limit` | Events per page, 1 to 200 (default 50) | | `--cursor` | Continue after a previous page, from its `Next cursor:` line | ## aether review verification List the verification recorded against the pull request (tests, typechecks, lints, browser checks and preview sessions), newest first, with the pull request's current head. An event recorded against another commit is marked `(older)`. ## aether review proof Show everything recorded as proof of the pull request: who may watch it, whether you may curate it, the tasks that published it, its review runs with the verdict each posted and the head it reviewed, and how many findings and capture claims it holds. A pull request named by repository and number is resolved among the proof's own owners. `aether review proof visibility ` sets who may watch the proof: `org` keeps it to the organization, `public` opens it to anyone with its link. The creator of a task linked to the pull request, or an admin or owner of its organization, may set it. ```bash theme={"dark"} aether review proof visibility acme/web#42 public ``` ## aether review run Ask Aether to review the pull request at its current GitHub head, even an unchanged one. The pull request's review run reviews again, or a first one starts; repeating the request at one head delivers one instruction. ```bash theme={"dark"} aether review run acme/web#42 ``` ``` Review run #3 of acme/web#42 is reviewing (task 8c7b6a59-4d3e-4f2a-9b1c-0d9e8f7a6b5c). ``` ## aether review submit Submit a review through your own GitHub identity, pinned to the head you reviewed (`aether review pr` shows the head). | Flag | Description | | - | - | | `--verdict` | `approve`, `request-changes` or `comment` (required) | | `--head` | The head commit you reviewed (required); a head that moved past it is refused with `head_moved` | | `--body` | The review's text; `request-changes` and `comment` need one | ```bash theme={"dark"} aether review submit acme/web#42 --verdict approve --head 3f2a9c1e5b7d4f6a8c0e2b4d6f8a0c2e4b6d8f0a ``` ## aether review comment Post a top-level comment on the pull request, printing the comment GitHub created. | Flag | Description | | - | - | | `--body` | The comment's text (required) | ## aether review reviewer Request a review from a GitHub user, or withdraw one, through your own GitHub identity. Requesting one already requested, or withdrawing one not requested, changes nothing. ```bash theme={"dark"} aether review reviewer add acme/web#42 octocat aether review reviewer remove acme/web#42 platform --team ``` | Flag | Description | | - | - | | `--team` | The name is an organization team's slug, not a user's login | ## Refusals A refusal prints the API's message; with `--json` it is `{"error": {"code": "...", "message": "..."}}` with the API's code. The ones these commands meet most: | Code | Meaning | | - | - | | `org_role_insufficient` | Your role cannot do this: a billing member reads no pull request, and a viewer reads but does not act | | `control_forbidden` | Only a linked task's creator, or an admin or owner, may set a proof's visibility | | `org_id_required` | More than one of your organizations owns the pull request; name one with `--org` | | `github_identity_required` | The action goes through your GitHub identity, and you have none connected | | `github_push_access_required` | Merging, and a fix request to a review run, need push permission on the repository | | `head_moved` | The pull request's head moved past the `--head` you pinned on `submit` or `diff` | | `conflict` | A 409 with no code of its own: `pr merge` refused because the head moved past `--head` or GitHub would not merge, or a `snapshot` of a head and base the pull request no longer names | | `validation_failed` | A value the API cannot take, or GitHub refusing the action, with GitHub's message | | `pull_request_closed` | A review run was asked for on a closed or merged pull request | | `project_required` | No project is connected to the pull request's repository | | `pr_review_actor_required` | The project has no review actor to create review runs as | | `no_dispatch_target` | The pull request has no task or review run to dispatch its feedback to | A pull request that does not exist, one none of your organizations owns, and one whose repository you can no longer reach on GitHub all answer the same not found. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.