pr-rocket CLI

Get PR Rocket's code review of your local changes before you open a pull request.

uv tool install 'git+https://github.com/pydantic/pr-rocket#subdirectory=cli'
pr-rocket login     # approve the sign-in in your browser
pr-rocket review

review sends every file that differs from where your branch forked from origin's default branch (git merge-base HEAD origin/<default>): unpushed commits, staged, unstaged and untracked files. That base is always a pushed commit, so it works from any local branch. Use --base REF to review against something else. The review takes a few minutes. Findings are printed worst first, and the command exits 1 when there are any. Nothing is posted to GitHub.

Binary files, symlinks, submodules and files over 1 MB are not sent, and one review uploads at most 4,000,000 characters in total.

pr-rocket review [PATH] reviews the checkout containing PATH (default .). Exit codes: 0 no findings, 1 findings, 2 an error or nothing reviewable (every changed file was skipped), 3 PR Rocket doesn't review this repo (it isn't installed there, or the repo's code review is off). The CLI asks the server about the repo first, so in that case nothing is uploaded. pr-rocket logout forgets the saved key.

Coding agents

Agents can run the CLI in a shell. --json prints the result as JSON:

pr-rocket review --json

Run pr-rocket login once in a terminal, or give the agent's environment PR_ROCKET_TOKEN. An agent can also run pr-rocket login --no-browser and hand you the link it prints to approve. An agent that gets exit code 3 should skip the review: the repo isn't one PR Rocket reviews.

Access

pr-rocket login signs in through your browser. It prints a code such as BCDF-GHJK and opens Ground Control's sign-in page, which shows the same code and this machine's name. Approve it there (signing in with GitHub first if you need to), and the CLI collects a new key, named after the machine, that lasts 90 days. The code expires after 10 minutes. On a machine without a browser (over SSH, in a container), open the printed link on any device instead; --no-browser only prints it.

The key is saved in $XDG_CONFIG_HOME/pr-rocket/credentials.json (default ~/.config, mode 0600). PR_ROCKET_TOKEN overrides the saved key, for CI and agents. You can see and revoke keys in Ground Control under CLI keys at any time.

You can also make a key by hand in Ground Control under CLI keys (choosing 30 days, 90 days or a year) and pipe it in (echo prk_... | pr-rocket login), or paste it with pr-rocket login --paste.

A key acts as you. To review a repo you need three things:

• approved Ground Control access;
• GitHub read access to the repo;
• PR Rocket installed on the repo, with Code review on in its Ground Control settings.

Each person can have two reviews running at a time, and 50 per hour.

Set PR_ROCKET_URL (or pass --server, before the subcommand: pr-rocket --server URL review) to use another PR Rocket instance.

Your own Codex plan

pr-rocket codex connect      # sign in to ChatGPT in the browser, then upload the sign-in
pr-rocket codex status
pr-rocket codex disconnect   # delete it from PR Rocket

connect lets PR Rocket do its work on the pull requests you author (reviews, summaries, titles), and the pr-rocket review runs you start, on your own ChatGPT/Codex plan instead of its API account. A request your plan can't serve (its usage limit, a model it doesn't offer, a sign-in that stopped working) goes to the API account instead, and a usage limit pauses your plan for 15 minutes. It's a separate ChatGPT sign-in from codex login (same browser flow, callback on localhost:1455), so it never logs your local Codex out. PR Rocket stores the tokens encrypted, and disconnect deletes them. It asks for your consent first; --yes skips the prompt.

Run pr-rocket login first: the CLI key says whose PRs the plan is for. Approve the ChatGPT sign-in in a browser on the same machine, since it calls back to that machine's localhost:1455; connect gives up after 5 minutes without it.

Development

just cli-check from the repo root formats, lints, type-checks and tests this package.

Releasing

The CLI is published to PyPI as pr-rocket by .github/workflows/publish-cli.yml, with PyPI trusted publishing (no stored token). Bump version in cli/pyproject.toml, merge, then tag that commit on main: git tag cli-v<version> && git push origin cli-v<version>. The workflow checks the tag matches the version, runs the tests, builds and publishes.