neo pr
Manage pull requests
neo pr [OPTIONS] <COMMAND>neo pr create
Section titled “neo pr create”Open a pull request.
The source branch defaults to the current git branch.
neo pr create [OPTIONS] --title <TITLE> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--title |
<TITLE> |
yes | Pull request title, and the only required flag here. Say what the change does and why — it is what a reviewer sees before opening anything; the detail belongs in --body |
|||
--body |
<BODY> |
no | "" |
Markdown description | ||
--base |
<BASE> |
no | Target branch the PR merges into. Defaults to the repo’s default branch when omitted | |||
--head |
<HEAD> |
no | Source branch. Defaults to the current git branch | |||
--draft |
no | Open as a draft | ||||
--json |
no | Print the raw response as JSON |
neo pr list
Section titled “neo pr list”List pull requests
neo pr list [OPTIONS] [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--state |
<STATE> |
no | open |
open, merged, closed, all |
Which pull requests to list | |
--json |
no | Print the raw response as JSON |
neo pr view
Section titled “neo pr view”Show one PR with its diffstat, reviews and comments.
The diffstat is merge-base-aware (three-dot, the same range the merge would apply) and its totals cover the whole diff even when the file list is capped; the trailing line says which cap applied.
neo pr view [OPTIONS] <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--json |
no | Print {pull_request, checks, diffstat, reviews, comments} as JSON |
neo pr context
Section titled “neo pr context”Agent context pack for a pull request (always JSON).
The PR plus its checks roll-up, review comments and inline threads, a per-file change summary (paths and line counts, no patch text), and the issues it links to. Bounds are reported in truncated.
neo pr context [OPTIONS] <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
neo pr wait
Section titled “neo pr wait”Block until a PR reaches a terminal state, printing status transitions.
The first-class replacement for a shell loop around neo pr view: one process, and a distinct exit code per outcome instead of grepping prose. It wakes on the repo’s event stream, so a check going green is usually noticed in a second or two rather than at the next poll.
Exit codes: 0 the condition held · 3 a check failed, contexts listed (--for checks) · 4 closed without merging · 5 every check finished and the merge gate still refuses, with the server’s reasons (--for merged) · 6 timed out · 7 every check was skipped, so nothing ran (--for checks) · 1 the command itself failed.
The check set folds BOTH sources the merge gate judges — workflow runs and externally-posted commit statuses — so a red external status cannot read as green.
neo pr wait [OPTIONS] <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--for |
<WAIT_FOR> |
no | checks |
checks, merged |
What to wait for. checks (the default) waits for CI on the PR’s head to finish — a question that always answers itself. merged waits for the PR to land, which needs auto-merge armed or a human, so it warns when nothing is armed and gives up once CI has finished and the merge gate still refuses. |
|
--timeout |
<TIMEOUT> |
no | 3600 |
Maximum seconds to wait (at most 7 days) | ||
--interval |
<INTERVAL> |
no | 30 |
Poll interval in seconds. Values below the floor (30) are raised to it with a warning — replacing hot polling is the point of the command. This is the read cadence only when the forge’s event stream is unavailable (an older deploy, a proxy that will not pass text/event-stream, an exhausted stream budget). With the stream connected the command wakes on events and the timer is a backstop on a longer period, so a lost event costs latency and never a hang. A value above that backstop still wins. |
neo pr merge
Section titled “neo pr merge”Merge a PR.
The freshly fetched head commit is sent as a stale guard, so a concurrent push turns the merge into an error.
neo pr merge [OPTIONS] <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--auto |
no | Arm merge-when-green instead of merging now: the PR merges the moment required checks and reviews pass. Merges immediately if the gate is already green, so it is safe to pass unconditionally | ||||
--merge |
no | Land it as a two-parent merge commit. Omit both this and --squash to use the repository’s default method. Neither can be combined with --auto: the arming endpoint carries no body, so an armed merge takes the repository default at the moment it fires. |
||||
--squash |
no | Land it as ONE commit carrying the whole change, authored by the source head’s author, with Co-authored-by: trailers for everyone else on the branch. Refused for a PR with stacked children |
||||
--json |
no | Print the resulting pull request as JSON. With --auto that is usually the armed PR, but the server merges on the spot when the gate is already green — so read status rather than assuming which of the two came back |
neo pr update-branch
Section titled “neo pr update-branch”Update a PR’s branch by merging the target into it.
The freshly fetched head commit is sent as a stale guard, so a concurrent push turns the update into an error.
neo pr update-branch [OPTIONS] <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--json |
no | Print what the update DID as JSON — {outcome, new_head}, not a pull request. outcome is updated or already_up_to_date, and new_head carries the source branch’s new head commit exactly when the branch moved |
neo pr close
Section titled “neo pr close”Close a PR without merging
neo pr close [OPTIONS] <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--json |
no | Print the closed pull request as JSON |
neo pr comment
Section titled “neo pr comment”Comment on a PR
neo pr comment [OPTIONS] --body <BODY> <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--body |
<BODY> |
yes | Markdown comment body | |||
--json |
no | Print the created comment as JSON |
neo pr review
Section titled “neo pr review”Submit a review decision on a PR
neo pr review [OPTIONS] <--approve|--request-changes|--comment> <NUMBER> [TARGET]| Option | Value | Required | Default | Env | Values | Description |
|---|---|---|---|---|---|---|
<NUMBER> |
yes | Pull request number (the 42 in acme/api#42) |
||||
<TARGET> |
no | <owner>/<repo> or bare <repo>. Inferred from a checkout remote pointing at this host when omitted |
||||
--approve |
no | Approve the PR | ||||
--request-changes |
no | Request changes | ||||
--comment |
no | Comment-only review (no approval state change) | ||||
--body |
<BODY> |
no | "" |
Optional review summary (Markdown) | ||
--json |
no | Print the submitted review as JSON |