CLI reference
Flags, environment variables, and exit codes of the CI-facing patchlight commands.
npx @patchlight/sdk <command> [options]
# or, with the package installed: patchlight <command> [options]These are the non-interactive commands, shipped with @patchlight/sdk for CI. They behave
identically when run from @patchlight/cli, which delegates them to this same
implementation — so a pipeline does not change meaning when a developer installs the interactive
package. The scan picker, the fullscreen UI, and keyboard triage are only in @patchlight/cli.
Environment variables
| Variable | Description |
|---|---|
PATCHLIGHT_API_KEY | API key. Required in CI; overrides a stored patchlight login |
PATCHLIGHT_BASE_URL | API origin override. Default https://api.patchlight.dev |
PATCHLIGHT_CONFIG_DIR | Where a stored login is read from. Default ~/.patchlight |
patchlight review
Submits the current git diff for review.
| Flag | Description |
|---|---|
--base <ref> | Base ref to diff against. Default: auto-detected from CI env (GitHub Actions, GitLab CI, Bitbucket, Azure), then origin/HEAD, then HEAD~1 |
--repo <name> | Repository name shown in the dashboard. Default: parsed from the origin remote |
--diff <path|-> | Read a unified diff from a file (or stdin with -) instead of running git |
--no-files | Skip uploading changed-file contents as review context |
--ref <sha> | Reviewed commit. Default: HEAD |
--title <text> | Human-readable review title |
--wait | Poll until the review finishes and print findings |
--timeout <sec> | Max seconds to wait (default 900; implies --wait) |
--fail-on <severity> | Exit 1 when findings at/above this severity exist: info, low, medium, high, critical (implies --wait) |
--json | Machine-readable JSON output |
--base-url <url> | API origin override |
The submission is idempotent per commit: retrying a CI job for the same repo + commit returns
the already-created review instead of starting a duplicate.
patchlight status <reviewId>
Prints the status of a review; when it's done, also prints the summary and findings. Supports
--json. Exits 2 when the review failed or was skipped by a spend cap.
patchlight scan <repo>
Starts a security scan of a whole repository. Unlike review, this needs no local checkout — the
scan runs against the connected GitHub repo.
patchlight scan acme/checkout-service --wait --fail-on high<repo> accepts either the owner/repo name shown by patchlight repos or a repository id.
Scans require a connected GitHub repository; repos created implicitly by patchlight review
have no git connection and cannot be scanned.
| Flag | Description |
|---|---|
--wait | Poll until the scan finishes and print findings |
--timeout <sec> | Max seconds to wait (default 900; implies --wait) |
--fail-on <severity> | Exit 1 when findings at/above this severity exist (implies --wait) |
--json | Machine-readable JSON output |
--base-url <url> | API origin override |
Only one scan per repository runs at a time; starting a second while one is in flight exits 4
with already_running.
patchlight scan-status <scanId>
Prints the status of a scan; when it's done, also prints its cost and findings. Supports --json.
patchlight finding <id> --status <status>
Triages a finding — open, resolved, or dismissed. Works for both review and scan findings.
Finding ids are printed by patchlight review --wait, patchlight scan --wait and
patchlight findings.
patchlight finding 6f2c… --status dismissedRead commands
| Command | Description |
|---|---|
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 — the env var, or a stored login |
All of them accept --json and --base-url.
Credential commands
| Command | Description |
|---|---|
patchlight logout | Forget a login stored in ~/.patchlight |
patchlight login is not in this package — a browser sign-in needs the interactive UI, so it lives
in @patchlight/cli. In CI you want PATCHLIGHT_API_KEY regardless.
Exit codes
| Code | Meaning |
|---|---|
0 | Clean, or no findings at/above --fail-on |
1 | Findings at or above the --fail-on threshold |
2 | Review or scan failed, timed out, was skipped, or an unexpected error occurred |
3 | Usage or authentication error (bad flags, missing/invalid/out-of-funds key) |
4 | Transient — the workspace is busy or the platform is briefly unavailable. Safe to retry |
Exit 4 is new in 0.2.0 and covers too_many_pending_reviews, already_running, and 503
responses, which previously exited 2. 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 (or enough depth) in the job, e.g. fetch-depth: 0 on GitHub
Actions or 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.