@patchlight/cli

Patchlight in your terminal: AI security scanning of the code on your disk right now — uncommitted work included — with findings streaming in one at a time and keyboard triage when they land.

Node.js 18.17+.

npm install -g @patchlight/cli
patchlight login
cd your-repo && patchlight scan --diff

Why this and not @patchlight/sdk

They are the same product with different jobs.

| | @patchlight/sdk | @patchlight/cli | |---|---|---| | For | CI pipelines | developers at a terminal | | Runtime dependencies | zero | ink, react, highlight.js | | Auth | PATCHLIGHT_API_KEY | patchlight login (browser) | | Output | plain text / --json | live TUI, then triage |

Everything non-interactive — review, status, findings, repos, balance, --fail-on — behaves identically here, because this package delegates those commands to the SDK's own implementation rather than reimplementing them. Installing this does not change what your pipeline does.

Sign in

patchlight login

Opens a browser, shows you a short code to confirm, and stores a token in ~/.patchlight/credentials.json (mode 0600). No secret passes through your shell history, and the machine appears in the dashboard under API Keys where you can revoke it.

Headless box or over SSH? The code and URL are always printed — open them anywhere you are signed in.

PATCHLIGHT_API_KEY still wins when it is set, so a CI job on a machine somebody once logged into uses the credential its pipeline configured.

Scan

patchlight scan

Asks what to scan, then runs it:

• Changed files — what this branch touched, uncommitted work included. Seconds and cents. This is the one to run on every push.
• Whole repository — every scannable file here. The monthly one.
• A directory — one subtree.

Skip the picker with flags:

patchlight scan --diff              # changed files
patchlight scan --diff --base main  # against an explicit base
patchlight scan --path src/api      # one subtree
patchlight scan --no-neighbours     # with --diff, changed files only

What happens

1. Local walk — instant, no network. Skips node_modules, build output, lockfiles and binaries.
2. Preflight — checks your balance and the size caps before a single byte of code is uploaded.
3. Upload — a bounded snapshot of the working tree.
4. Triage — how much of it is worth reading, summarised by weakness family.
5. Findings — streamed as the model completes them, not batched to the end.

All of it runs fullscreen, and the terminal you started in is left exactly as it was when you quit — with a short summary of what was found printed under your prompt.

Triage

When the scan ends you are already in it — no second command, nothing to copy. Each finding shows the offending lines read from your disk, syntax highlighted by highlight.js on a tinted block with the flagged line picked out, and the suggested fix underneath — code highlighted, advice as plain text.

↑↓ move · d dismiss · r resolve · u reopen · o open in $EDITOR · q quit

g / G jump to the first and last finding; PgUp / PgDn move a page at a time. o hands the terminal over to $EDITOR at the right line and takes it back when you quit — vim, code, cursor, subl and zed all get the argument form they actually want.

Triage writes through to the same place the dashboard reads, so a dismissal here is a dismissal everywhere.

--diff is the one to learn

A full-repo scan is a monthly thing. A branch scan is a per-push thing: it reads only what you changed (plus same-directory siblings, so cross-file flows are still visible), takes seconds, and costs cents. It also sees code you have not committed — which a server that clones your repository structurally cannot.

Non-interactive use

Piping or redirecting output turns off the picker, the fullscreen UI and the triage keys: the scan runs whole-repo and prints one plain report.

patchlight scan --diff > scan.log

| Exit code | Meaning | |-----------|---------| | 0 | Scan completed | | 1 | Findings at or above --fail-on (the delegated CI commands) | | 2 | Scan failed | | 3 | Usage/authentication error | | 4 | Transient — safe to retry |

Environment

| Variable | Meaning | |---|---| | PATCHLIGHT_API_KEY | API key; overrides a stored login | | PATCHLIGHT_BASE_URL | API origin override | | 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 |

Privacy

patchlight scan uploads the text files of your working tree, under the skip rules and size caps above, to the Patchlight API for analysis. It never uploads binaries, lockfiles, dependency directories, or anything outside the repository root. Use --path or --diff to narrow what is sent.

Documentation

https://patchlight.dev/docs/cli

License

MIT