Commands

The CLI exposes one subcommand: analyze. Everything you can do with the binary flows through it. Each section below documents flags, defaults, and the smallest invocation that demonstrates them.

prcompass --help                # top-level
prcompass analyze --help        # subcommand
prcompass --version             # prints "0.1.0"

`prcompass analyze`

Analyse a git diff. Outputs JSON to stdout by default; pass --format human for a terminal-friendly summary.

prcompass analyze [options]

Required flags

Flag	Default	Meaning
`--repo <path>`	`process.cwd()`	Path to a local git repository. Resolved to an absolute path before being passed to the adapter.

Exactly one of the following two flags is also required:

Flag	Meaning
`--diff <range>`	Git diff range. See diff range syntax for accepted forms.
`--github <owner/repo#number>`	Analyze a GitHub pull request, e.g. `nkwib/pr-analyze#42`. Needs `GITHUB_TOKEN` (or `GH_TOKEN`) in the environment, and a local clone at `--repo` with the PR's base and head commits already fetched (e.g. `gh pr checkout <n>`).

Passing both, or neither, is an error.

prcompass analyze --repo . --diff HEAD~1..HEAD
GITHUB_TOKEN=... prcompass analyze --repo . --github nkwib/pr-analyze#42

Optional flags

Flag	Default	Meaning
`--local`	`true`	Cosmetic; `--diff` always implies the `LocalAdapter`. Has no effect on its own.
`--format <kind>`	`json`	One of `json` \| `human`. `human` writes a terminal summary; `json` is pipe-friendly.
`--pretty`	`false`	Pretty-print JSON output with 2-space indent. No effect when `--format human`.
`--max-commits <n>`	`5000`	Cap commit-history walk. Higher values trade analysis latency for older history.

Examples

# Default — compact JSON to stdout
prcompass analyze --repo . --diff HEAD~1

# Human summary on the terminal
prcompass analyze --repo . --diff main..HEAD --format human

# Pretty JSON for inspection
prcompass analyze --repo . --diff HEAD~5 --pretty

# Cap commit walk on a large repo (faster but lower-resolution churn / cochange)
prcompass analyze --repo /path/to/big-repo --diff main..feature --max-commits 1000

# Pipe the result into jq
prcompass analyze --repo . --diff HEAD~1 | jq '.triage.verdicts | group_by(.verdict) | map({verdict: .[0].verdict, count: length})'

# Analyze a GitHub PR against a local clone that already has it fetched
gh pr checkout 42
GITHUB_TOKEN=... prcompass analyze --repo . --github nkwib/pr-analyze#42

What it runs

Behind the scenes, analyze does:

For --diff, resolves the range into (baseSha, headSha) via git rev-parse. For --github, fetches the PR from the GitHub REST API to get (baseSha, headSha) and PR metadata, then resolves those SHAs the same way.
Calls the configured adapter's collect() method to produce an AnalyzeContext (commits + diff + optional PR metadata). Commit history and the diff itself always come from the local clone at --repo, for both flags.
Runs the deterministic engine from @prcompass/core (mining → churn → cochange → hotspots → risk).
Runs the file triage from @prcompass/pr-triage-filter over the diff files.
Serialises the combined output (CliAnalysisOutput).

Each step is deterministic — same inputs, same bytes out. See the output schema for what each step contributes.

Help text

The CLI uses commander internally. --help is generated automatically:

$ prcompass --help
Usage: prcompass [options] [command]

PR Compass CLI — deterministic OSS analysis of a git diff against the
repo's history.

Options:
  -V, --version       output the version number
  -h, --help          display help for command

Commands:
  analyze [options]   Analyse a git diff. Outputs JSON to stdout by
                      default; pass --format human for a terminal-friendly
                      summary.
  help [command]      display help for command

$ prcompass analyze --help
Usage: prcompass analyze [options]

Options:
  --repo <path>                 path to a local git repository (default: cwd)
  --diff <range>                git diff range (e.g. "HEAD~1..HEAD",
                                 "main..feature", or a single ref interpreted
                                 as "<ref>..HEAD"). Mutually exclusive with
                                 --github.
  --github <owner/repo#number>  analyze a GitHub pull request, e.g.
                                 "nkwib/pr-analyze#42". Needs GITHUB_TOKEN (or
                                 GH_TOKEN) in the environment and a local
                                 clone at --repo with the PR base and head
                                 commits already fetched. Mutually exclusive
                                 with --diff.
  --local                       use the LocalAdapter (implied by --diff)
                                 (default: true)
  --format <kind>               output format (choices: "json", "human",
                                 default: "json")
  --pretty                      pretty-print JSON output
  --max-commits <n>             cap commit history walk (default: "5000")
  -h, --help                    display help for command

Future commands

The package's surface is deliberately one command for v0.1.x. Future commands (e.g. prcompass diff, prcompass risk) would each take a focused slice of the analysis output rather than re-running the pipeline. None are scheduled at the time of writing.