Skip to content
xiv

xiv pr

The PR family: pr review (inbound review), pr fix (one-shot fixes), and pr refine (bounded settle loop). None of them ever merges a PR.

The axis that separates them is does code get changed and pushed? review is inbound — it evaluates someone's PR and posts comments, never code. fix and refine are outbound — they change your code and push it.

CommandDirectionPushes code?Use for
xiv pr review [N]inboundno (comments only)reviewing a PR, usually someone else's
xiv pr fix [N]outbound, one-shotyes, onceapplying the findings already on a PR, then stopping
xiv pr refine [N]outbound, bounded loopyessettling a PR against CI + human comments

All three take an optional PR number. review with no number lists open PRs to pick from; fix and refine with no number default to the current branch's PR (and error if the branch has none).

xiv pr review

Review a remote PR locally: an agent reviews it in an isolated worktree, then you interactively select findings and submit.

xiv pr review [prNumber] [--repo <owner/name>] [--prompt-file <path>] [--keep] [--auto-submit]
 
# examples
xiv pr review                      # pick from a list of open PRs in this repo
xiv pr review 1234
xiv pr review 88 --repo acme/api   # a repo you're not in; auto-cloned

What happens

  1. Resolve the repo — the current directory's repo, or --repo owner/name (auto-cloned under SMITHERS_HOME if not present locally).
  2. Pick the PR — the given number, or an interactive list of open PRs.
  3. Prepare an isolated worktree — the PR's head is checked out in its own git worktree, so your working tree is never touched.
  4. Run the review agent — it reads the diff in that worktree (this can take a few minutes) and produces a suggested verdict plus structured findings, each with a severity (blocker, high, medium, low, nit), an optional file:line, and whether it can be an inline comment.
  5. You decide, interactively:
    • the review type — comment, approve, request changes, or "don't submit (keep notes only)";
    • which findings to include (nits are deselected by default);
    • whether findings with a file:line become inline comments;
    • the top-level body, opened in your editor ($VISUAL / $EDITOR);
    • a final confirmation before anything is posted.
  6. Submit via gh. If GitHub rejects the inline comments, it retries once with the findings folded into the body, so a review is never lost.

Findings and the draft body are saved to a per-PR scratch directory under SMITHERS_HOME, so cancelling keeps your notes. The worktree is removed afterward unless --keep.

Flags

FlagDefaultWhat it does
--repo <owner/name>current directory's repoTarget repo; auto-cloned if not present locally.
--prompt-file <path>the packaged local-review promptPath to a custom review-prompt template (Markdown), resolved relative to your current directory.
--keepoffKeep the review worktree after submitting (default: remove it).
--auto-submitoffSkip the interactive prompts and submit the agent's verdict with all inline-able findings.

The judgment of what's worth flagging comes from the xiv-review-core skill; pr review is the CLI that pulls the PR into a worktree and submits. If you only want findings printed and nothing pulled or posted, use the skill directly.

xiv pr fix

Address the existing review findings on a PR once and push — no loop, nothing posted back.

xiv pr fix [prNumber]
 
# examples
xiv pr fix          # the current branch's PR
xiv pr fix 1234

Launches the pr-fix workflow: it reads the findings already on the PR (across all comment surfaces), fixes the valid ones with real changes and tests, commits, and pushes once. It does not wait for CI, does not re-request review, and does not comment. With no number it uses the current branch's PR, erroring if there isn't one.

Use it when the feedback is in and you want it applied — then you take over.

xiv pr refine

Settle a PR against CI and human review comments: read its checks and comments, fix what they raise, and push.

xiv pr refine [prNumber] [--branch <name>] [--base <branch>]
 
# examples
xiv pr refine                     # the current branch's PR
xiv pr refine 1234
xiv pr refine --branch eng-123-fix-thing --base main   # push a branch and open its PR first

Launches the pr-review-loop workflow. It takes a snapshot of the PR's status checks and its human review comments, fixes what they raise (real changes plus tests), and pushes — a bounded settle loop, not an open-ended wait: a still-running build ends the round and is reported honestly rather than polled. It never merges, never comments, never tags anyone.

Flags

FlagDefaultWhat it does
--branch <name>—Branch to push and open as a new pull request first, then settle. Mutually exclusive with a PR number.
--base <branch>mainBase branch for that newly opened pull request.

Passing both a PR number and --branch is an error. With neither, it uses the current branch's PR.

When to use which

  • "Review X", "take a look", "leave comments" → pr review. It changes no code.
  • "Apply the review comments and push", once, no babysitting → pr fix.
  • "Get CI green", "handle the comments on my PR" → pr refine.
  • "What's wrong with this change", nothing run or posted → the xiv-review-core skill, no CLI at all.
  • An xiv implement branch you now want published → pr refine --branch <name> (opens the PR) rather than re-running ship.

fix and refine mutate and push code; don't reach for them when the request was only to evaluate.

Suggest changes to this page