Command reference
Every patchlight command, flag, environment variable, and exit code.
patchlight <command> [options]Run patchlight with no arguments to go straight to the scan picker.
Interactive commands
These live in @patchlight/cli.
| Command | Description |
|---|---|
patchlight | Pick what to scan, then triage the results |
patchlight scan | The same, with flags to skip the picker |
patchlight login | Sign in from this machine (opens a browser) |
patchlight logout | Forget the stored login |
patchlight report <id> | Print a finding as private-disclosure markdown |
patchlight scan
Scans the working tree. With a <repo> positional it instead runs the SDK's server-side scan
of a connected GitHub repository — see patchlight scan <repo> below.
| Flag | Description |
|---|---|
--diff | Scan only what this branch changed, uncommitted work included |
--base <ref> | Base ref for --diff. Default: auto-detected |
--no-neighbours | With --diff, don't also read same-directory siblings |
--path <dir> | Scan one subdirectory |
--repo <name> | Name to file the findings under. Default: from the origin remote |
--base-url <url> | API origin override |
patchlight report <id>
Writes the finding to stdout as disclosure-ready markdown; the advisory URL and any progress
chatter go to stderr, so patchlight report <id> | pbcopy stays clean.
The finding is looked up in the workspace's recent findings — which is where one you just scanned will be.
CI and scripting commands
These are identical in both packages: @patchlight/cli delegates them verbatim to
@patchlight/sdk, so a pipeline behaves the same whichever is installed.
| Command | Description |
|---|---|
patchlight review [options] | Submit the current git diff for review |
patchlight status <reviewId> | Status, and findings once it is done |
patchlight scan <repo> [options] | Start a server-side scan of a connected repo |
patchlight scan-status <scanId> | Status, cost, and findings of a scan |
patchlight finding <id> --status <status> | Triage: open, resolved, dismissed |
patchlight repos | Repository ids, names, and monitor/index flags |
patchlight reviews | Recent reviews, newest first |
patchlight findings | Recent findings across the workspace |
patchlight balance | Remaining USD balance |
patchlight whoami | Which credential is in use |
Full flag tables for these live in the SDK CLI reference. The short version:
| Flag | Applies to | Description |
|---|---|---|
--wait | review, scan <repo> | Poll until it finishes, then print findings |
--timeout <sec> | review, scan <repo> | Max seconds to wait (default 900; implies --wait) |
--fail-on <sev> | review, scan <repo> | Exit 1 on findings at or above info|low|medium|high|critical (implies --wait) |
--json | all of them | Machine-readable output |
--base-url <url> | all of them | API origin override |
patchlight scan <repo>
<repo> is either the owner/repo name shown by patchlight repos, or a repository id.
Server-side scans need a connected GitHub repository — a repo entry created implicitly by
patchlight review has no git connection and cannot be scanned. Use patchlight scan --diff
(no positional) to scan a local checkout instead.
Only one scan per repository runs at a time; starting a second while one is in flight exits 4
with already_running.
Environment variables
| Variable | Meaning |
|---|---|
PATCHLIGHT_API_KEY | API key; overrides a stored login |
PATCHLIGHT_BASE_URL | API origin override. Default https://api.patchlight.dev |
PATCHLIGHT_CONFIG_DIR | Credential directory. Default ~/.patchlight |
EDITOR / VISUAL | Used by o in triage |
NO_COLOR / FORCE_COLOR | Standard colour control, honoured by the whole UI |
Exit codes
| Code | Meaning |
|---|---|
0 | Clean, or no findings at or above --fail-on |
1 | Findings at or above the --fail-on threshold |
2 | The review or scan failed, timed out, or was skipped by a spend cap |
3 | Usage or authentication error — bad flags, missing/invalid/expired credential |
4 | Transient: the workspace is busy or the platform is briefly unavailable. Safe to retry |
Exit 4 covers too_many_pending_reviews, already_running, and 503 responses, which exited
2 before 0.2.0. When the API sends a Retry-After, the CLI prints how long to wait. Pipelines
that only check for a non-zero exit are unaffected.
Shallow clones
Base-ref detection uses git merge-base, which needs history. Most CI providers clone shallowly by
default — fetch full history in the job (fetch-depth: 0 on GitHub Actions, GIT_DEPTH: "0" on
GitLab). With a depth-1 clone the CLI falls back to diffing directly against the base ref, which
can overstate the change set.