pr-lens

pr-lens analyze --base ref [options]pr-lens render graph.json [options]pr-lens comment --graph file --manifest file [options]pr-lens validate file ...pr-lens export graph.json [options]

pr-lens is the command-line entry of PR Lens: it turns a Git diff into a schema-valid graph, draws animated architecture and data-flow SVGs, and composes the markdown that the GitHub App and Action post as a pull-request comment. The npm package is @coldtea/pr-lens-cli; the binary is pr-lens. Requires Node.js 20.11+.Only analyze talks to a model. The key is read from the environment and the diff is sent only to the named provider (Google Gemini, OpenAI, or any /chat/completions server via --base-url). Commit SHAs, the repository slug, pull-request number, and line counts are filled from Git; values the model writes there are discarded. If the answer fails the contract, validation errors are sent back once.render writes self-contained, deterministic SVGs (no script, no external references), a manifest of asset names, and drawn.graph.json (the document after corrections). comment prints markdown and does not post. export drops deleted nodes and delta annotations so a merged change can be committed as a snapshot map; nothing in the pipeline reads that map back.The same diagrams are also produced by the hosted GitHub App, the Action at coldteadotai/pr-lens/packages/action, and an agent skill (npx skills add coldteadotai/pr-lens).

-h, --help / -v, --version

Top-level help, or print the CLI version. Each subcommand also accepts --help.

Required. The change is measured against the merge base of this ref and --head, not the tip of the base branch.

Tip of the change (default HEAD).

Repository to read (default .). Slug is inferred from origin unless overridden.

gemini (default), openai, or openai-compatible.

Model id (required for openai-compatible), endpoint, and env var holding the key. Default keys: GEMINI_API_KEY or OPENAI_API_KEY. Never pass a key as a flag.

Repeatable. Lenses are architecture and data-flow (default both).

Recorded in provenance only.

Diff truncation (default 400000 bytes) and model output room (default 32768).

Report prompt size and send nothing.

Graph document path (default .pr-lens/graph.json).

Directory for SVGs, manifest.json, and drawn.graph.json (default .pr-lens/).

Default both.

Must be the drawn document the renderer wrote, plus its manifest (hash-checked).

Where published SVGs will be fetched from in the markdown.

Print only the hidden HTML comment used to find an existing PR Lens comment.

Omit the footer, or write markdown to a file instead of stdout.

Map path (default .github/pr-lens.map.json), map id, and commit it reflects.

On analyze and render: use or ignore .github/pr-lens.yml. analyze reads lenses from it; render applies rename/exclude/lane/group overlays.

.github/pr-lens.yml is picked up automatically. Typical keys:lenses

Which views analyze should fill.

Draw-time overlay (match paths or ids). Unmatched selectors are reported so a drifted config does not fail silently.

Footer on composed comments.

Misuse (unknown command, missing --base, bad flags) exits 2; other failures exit 1. Failure codes a script can branch on include USAGE, EMPTY_DIFF, MISSING_API_KEY, PROVIDER_FAILED, MODEL_OUTPUT_INVALID, GIT_FAILED, and INVALID_DOCUMENT.comment refuses a graph/manifest pair whose content hash does not match. OpenAI and OpenAI-compatible endpoints are separate --provider values because they disagree on max_tokens vs max_completion_tokens. The CLI does not install the GitHub App or post comments itself.

PR Lens is published by Coldtea AI (MIT). CLI package version around 0.1.3. Homepage https://prlens.dev.

git(1), git-diff(1), gh(1), mermaid(1)

Source code · Homepage · Documentation