Guide

The PR Compass CLI runs the deterministic OSS analysis pipeline over a git diff. Output is JSON by default (one document to stdout); pass --format human for a terminal-friendly summary.

ESM-only. Requires Node 20+ and git available on $PATH.

Install

# Global (provides the `prcompass` binary on PATH)
npm install -g @prcompass/cli

# Or run ad-hoc without installing
npx @prcompass/cli analyze --repo . --diff HEAD~1

The package is private: true in the source tree — when published, install via the public registry name once it ships.

Quick start

The most common invocation: analyse the last commit on the current branch.

prcompass analyze --repo . --diff HEAD~1

A single ref expands to <ref>..HEAD, so this is equivalent to --diff HEAD~1..HEAD.

# Compare your feature branch against main
prcompass analyze --repo . --diff main..feature

# Pretty-print JSON (no effect with --format human)
prcompass analyze --repo . --diff HEAD~1 --pretty

# Terminal-friendly summary
prcompass analyze --repo . --diff HEAD~1 --format human

The default output is one compact JSON document on stdout. Pipe it.

# What did the triage filter say?
prcompass analyze --repo . --diff HEAD~5 | jq '.triage.verdicts'

# Show only files with risk score >= 0.5
prcompass analyze --repo . --diff main | jq '.risk.byFile | to_entries | map(select(.value.score >= 0.5))'

Diff range syntax

--diff accepts the forms git rev-parse understands, with one shortcut.

Tags, remote refs (origin/main), and reflog references all work — anything git rev-parse can resolve in the configured --repo.

Adapters

The CLI ships two adapters. Both produce the same AnalyzeContext shape, so the same engine runs over either.

LocalAdapter (default)

Shells out to git against a local repository. No network. Used implicitly by the analyze command. Air-gap-safe.

prcompass analyze --repo /path/to/repo --diff main..HEAD

GitHubAdapter

Programmatic only — there is no --github flag. Use it when you have a local clone and want to enrich the result with PR metadata (number, title, author). You provide the Octokit client; the adapter never instantiates one for you.

import { GitHubAdapter, runAnalyzeCommand, formatJson } from '@prcompass/cli';
import { Octokit } from '@octokit/rest';

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const adapter = new GitHubAdapter({
  repoDir: '/abs/path/to/local-clone',
  octokit,
  owner: 'nkwib',
  repo: 'prcompass-cli',
  pullNumber: 42
});

const output = await runAnalyzeCommand(adapter);
process.stdout.write(formatJson(output, { pretty: true }));

The local clone is what feeds the deterministic engine — the GitHub API enriches the output with pr metadata, but does not influence the per-file metrics.

Exit codes

The CLI never exits non-zero based on what the analysis found — risk scores, hotspot counts, and triage verdicts are all data, not policy. Wrap the JSON in your own gate if you want to fail a build on, say, risk >= 0.8.

Where next

• Commands — every flag of analyze, with examples.
• Output schema — what's in the JSON document, key by key.
• Programmatic API — LocalAdapter, GitHubAdapter, runAnalyzeCommand, formatJson, formatHuman.
• Examples — jq recipes, GitHub Actions, CI gates.