CLI commands

Every patchlight command, flag, environment variable and exit code, for both the CLI and the SDK.

patchlight <command> [options]            # @patchlight/cli
patchlight-ci <command> [options]         # @patchlight/sdk, installed
npx @patchlight/sdk <command> [options]   # @patchlight/sdk, without installing anything

Commands

@patchlight/cli installs patchlight; @patchlight/sdk installs patchlight-ci (before SDK 0.5.0 it was also patchlight, so installing both globally failed). The interactive commands need the CLI; the rest behave identically in both, so patchlight review and patchlight-ci review are the same command.

Command	What it does	Package
`patchlight scan`	Scan the working tree, then triage	CLI
`patchlight login`	Sign in from this machine	CLI
`patchlight report <id>`	Print a finding as disclosure markdown	CLI
`patchlight review`	Submit the current git diff for review	both
`patchlight status <reviewId>`	Status of a review, and its findings once done	both
`patchlight scan <repo>`	Start a server-side scan of a connected repo	both
`patchlight scan-status <scanId>`	Status, cost and findings of a scan	both
`patchlight finding <id>`	Triage a finding	both
`patchlight repos`	Repository ids and names	both
`patchlight reviews`	Recent reviews, newest first	both
`patchlight findings`	Recent findings across the workspace	both
`patchlight balance`	Remaining USD balance	both
`patchlight whoami`	Which credential is in use	both
`patchlight logout`	Forget the stored login	both

Run patchlight with no arguments to open the scan picker (CLI) or the help text (SDK).

`patchlight scan`

Scans the working tree. See Scan in your terminal for the modes and triage keys.

Flag	Description
`--diff`	Scan only what this branch changed, uncommitted work included
`--base <ref>`	Base ref for `--diff`. Default: detected
`--no-neighbours`	With `--diff`, skip the other files in each changed directory
`--path <dir>`	Scan one subdirectory
`--repo <name>`	Name to file the findings under. Default: from the `origin` remote
`--fail-on <severity>`	Exit `1` on findings at or above `info`, `low`, `medium`, `high` or `critical`. Counts findings dismissed during triage too
`--base-url <url>`	API origin override

Without a terminal (piped, or in CI) it skips the picker and triage and prints the findings, so patchlight scan --diff --fail-on high works as a pipeline gate.

Opens a browser to sign in and stores a token in ~/.patchlight/credentials.json. Only in the CLI, since CI should use PATCHLIGHT_API_KEY.

patchlight whoami shows whether the environment variable or a stored login is in use.
patchlight logout forgets the stored login.

`patchlight report`

Writes a finding to stdout as private-disclosure markdown. The advisory URL and progress messages go to stderr, so patchlight report <id> | pbcopy stays clean. The finding is looked up in the workspace's recent findings.

`patchlight review`

Submits the current git diff for review.

Flag	Description
`--base <ref>`	Base ref to diff against. Default: from the CI environment, then `origin/HEAD`, then `HEAD~1`
`--repo <name>`	Repository name shown in the dashboard. Default: from the `origin` remote
`--diff <path\|->`	Read a unified diff from a file, or stdin with `-`, instead of running git
`--no-files`	Don't upload the changed files as review context
`--ref <sha>`	Reviewed commit. Default: `HEAD`
`--title <text>`	Review title
`--wait`	Wait for the review to finish and print the findings
`--timeout <sec>`	Max seconds to wait. Default `900`. Implies `--wait`
`--fail-on <severity>`	Exit `1` on findings at or above `info`, `low`, `medium`, `high` or `critical`. Implies `--wait`
`--json`	Machine-readable output
`--base-url <url>`	API origin override

The CI environment is read from GitHub Actions, GitLab CI, Bitbucket and Azure Pipelines. Submitting is idempotent per repository and commit, so a retried job returns the existing review.

`patchlight status`

Prints a review's status, and its summary and findings once it is done. Exits 2 if the review failed or was skipped by a spend cap. Supports --json.

`patchlight scan <repo>`

Starts a security scan of a connected GitHub repository. It needs no local checkout.

patchlight scan acme/checkout-service --wait --fail-on high

<repo> is the owner/repo name from patchlight repos, or a repository id. A repository that only exists because patchlight review created it has no git connection and cannot be scanned.

Takes --wait, --timeout, --fail-on, --json and --base-url, as for review. One scan per repository runs at a time; starting another exits 4 with already_running.

If part of the repository could not be read, the scan still finishes and a partial scan warning goes to stderr. It does not change the exit code. --json output carries the same information as windowsFailed / windowsTotal.

`patchlight scan-status`

Prints a scan's status, and its cost and findings once it is done. Supports --json.

`patchlight finding`

patchlight finding <id> --status dismissed

Sets a finding to open, resolved or dismissed. Works for review and scan findings. Ids are printed by review --wait, scan --wait and findings.

Read commands

repos, reviews, findings and balance print workspace data. All of them accept --json and --base-url.

Environment variables

Variable	Description
`PATCHLIGHT_API_KEY`	API key. Required in CI, and overrides a stored login
`PATCHLIGHT_BASE_URL`	API origin. Default `https://api.patchlight.dev`
`PATCHLIGHT_CONFIG_DIR`	Where the login is stored. Default `~/.patchlight`
`EDITOR` / `VISUAL`	Editor opened by `o` in triage (CLI)
`NO_COLOR` / `FORCE_COLOR`	Standard colour control (CLI)

Exit codes

Code	Meaning
`0`	Clean, or nothing at or above `--fail-on`
`1`	Findings at or above `--fail-on`
`2`	The review or scan failed, timed out or was skipped by a spend cap, or an unexpected error
`3`	Bad flags, a missing, invalid, expired or revoked credential, or insufficient funds
`4`	Busy or briefly unavailable. Safe to retry

Code 4 covers too_many_pending_reviews, already_running and 503 responses. When the API sends Retry-After, the command prints how long to wait.

Shallow clones

Finding the base branch uses git merge-base, which needs history. Most CI providers clone shallowly by default, so fetch full history (fetch-depth: 0 on GitHub Actions, GIT_DEPTH: "0" on GitLab). With a depth-1 clone the diff is taken against the base ref directly, which can make the change look bigger than it is.

On this page