Metadata-Version: 2.5
Name: pr-rocket
Version: 0.2.0
Summary: Review local changes with PR Rocket before opening a pull request
Project-URL: Homepage, https://pr-rocket.pydantic.dev
Author: Pydantic Services Inc.
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28
Description-Content-Type: text/markdown

# pr-rocket CLI

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

```
uvx pr-rocket login     # approve the sign-in in your browser
uvx pr-rocket review
```

`uvx` runs the CLI from [PyPI](https://pypi.org/project/pr-rocket/) without installing it
(`uvx pr-rocket@latest ...` picks up a newer release). To keep a `pr-rocket` command on your PATH instead,
`uv tool install pr-rocket` (`uv tool upgrade pr-rocket` to update); the commands below work the same without the `uvx`.

New here? Run the launch sequence:

```
uvx pr-rocket wizard
```

It signs you in (or keeps a saved key that still works), checks that you're on
PR Rocket's author allowlist and, if not, offers to open the pull request that adds
you (a `pr-rocket-join/<login>` branch on pydantic/pr-rocket, made with your own
`gh` sign-in; without `gh` or push access it opens the file in GitHub's editor and
says what to change), then offers to connect your ChatGPT/Codex plan. Every step
asks first: `--yes` accepts them all (the Codex consent too), and without a terminal
and without `--yes` they are declined (and with no saved key it stops rather than
wait for a browser sign-in), so it's safe in scripts. `--skip-allowlist`,
`--skip-codex` and `--no-browser` leave parts out. A brand-new person still needs a
PR Rocket admin to approve them in Mission Control before the browser sign-in goes
through.

`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.

`uvx 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. `uvx pr-rocket logout`
forgets the saved key.

## Coding agents

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

```
uvx pr-rocket review --json
```

Run `uvx pr-rocket login` once in a terminal, or give the agent's environment `PR_ROCKET_TOKEN`.
An agent can also run `uvx 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

`uvx 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_... | uvx pr-rocket login`), or
paste it with `uvx 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

```
uvx pr-rocket codex connect      # sign in to ChatGPT in the browser, then upload the sign-in
uvx pr-rocket codex status
uvx 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 `uvx 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 `uvx 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.
