# CLI The PullApprove CLI provides tools for configuring, validating, and testing your code review setup. It's installed as `pullapprove` (or `pa` for short). ## Installation Install the CLI globally using `uv`: ```bash uv tool install pullapprove ``` If you don't have `uv` installed: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ## Commands ### Configuration Management - `pullapprove init` - create a starter `CODEREVIEW.toml` - `pullapprove check` - validate configuration files ### File Matching and Testing - `pullapprove match` - show files and their matching scopes - `pullapprove match --changed` - show only changed files - `pullapprove match --diff` - show diff content with matches - `pullapprove match --by-scope` - organize output by scope instead of by path - `pullapprove match --scope ` - filter to show only files matching specific scopes - `pullapprove match --base ` - match your branch the way PullApprove would match a pull request into `` - `pullapprove match --author ` - apply each scope's `authors` as if `` opened the pull request - `pullapprove match --json` - output matches as JSON for scripts and other tools ### Coverage Analysis - `pullapprove coverage` - calculate file coverage for review scopes ## Examples ### Validate your configuration ```bash pullapprove check ``` Returns validation errors if your `CODEREVIEW.toml` has syntax issues or invalid settings. ### Test file matching for changed files ```bash pullapprove match --changed ``` Shows which review scopes would be triggered by files you've modified locally. ### Check review coverage ```bash pullapprove coverage ``` Displays what percentage of files in your repository are covered by review scopes. ### View specific scope matches ```bash pullapprove match --scope backend ``` Shows only files that match the "backend" scope, useful for testing scope patterns. ### Read matches from a script ```bash pullapprove match --diff --json ``` Prints the matches as JSON instead of text. Works with every other option except `--by-scope` and `--scope`, since the JSON is meant to have everything (filtering it in your script is easy). ```json { "scopes": { "backend": {"name": "backend", "reviewers": ["..."], "paths": ["api/**/*"], ...} }, "paths": { "api/views.py": {"path": "api/views.py", "scopes": ["backend"]}, "README.md": {"path": "README.md", "scopes": []} }, "code": { "": {"path": "...", "scopes": ["..."], "start_line": 12, "end_line": 12, "start_column": 1, "end_column": 30, "location_id": ""} } } ``` - `scopes` has the config of each scope that matched something, in config order. - `paths` has every file, with the scopes that own it by its `paths` patterns. A file only a `code` pattern matched has empty `scopes` here, and its scope is on its `code` entries, so to get every file in a scope, check both. - `code` has the lines matched by a scope's `code` patterns, keyed by location. ### Match a pull request in CI ```yaml # .github/workflows/pullapprove-scopes.yml on: pull_request jobs: pullapprove-scopes: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 - uses: astral-sh/setup-uv@v6 - run: uvx pullapprove match --json --base "$BASE_SHA" --author "$AUTHOR" > scopes.json env: BASE_SHA: ${{ github.event.pull_request.base.sha }} AUTHOR: ${{ github.event.pull_request.user.login }} ``` `scopes.json` has the scopes PullApprove will apply to the pull request, so you can hand them to another tool. - `on: pull_request` runs it when a pull request opens, gets new commits, or reopens, drafts included. Let it run on drafts instead of skipping them with an `if:`. Marking a draft ready doesn't change the commit, so the draft's run still counts, and if this job's check is in a scope's `unless`, a skipped run counts as not passing. - `--base` matches everything since your branch split off the base, against the `CODEREVIEW.toml` files on the base branch. That's what PullApprove uses too, so a pull request that edits the config is still matched against the config it's going *into*. - `fetch-depth: 0` is there because `--base` needs the history back to where the branch split off. Checking out the head commit (instead of the merge commit `actions/checkout` uses by default) matches the diff PullApprove sees. - If the base branch's `CODEREVIEW.toml` changes after the job runs, PullApprove picks that up right away, but `scopes.json` won't until the job runs again. For a pull request in a stack, PullApprove reads the configs from the bottom of the stack, which `--base` can't mirror (it would diff against that branch too). - `--author` only matters if your scopes use `authors`. If they list a team there, it'll stop with an error, because the CLI can't look up who's on a team. - `paths` matches come out the same as PullApprove's. Matches from `code` patterns can differ now and then, because GitHub labels each hunk with a function name differently than local git does. - If a pull request is so big that GitHub won't serve its diff, PullApprove reviews it as a [large-scale change](/docs/config/large-scale-change/) instead, which the CLI has no way of knowing. ## Automated Setup For automated configuration help, see the [Agents documentation](/docs/agents) which provides AI-powered assistance for setting up and migrating PullApprove configurations.