Scanning
What each scan mode reads, what leaves your machine, and how to triage the findings when they land.
Pick a mode
Run patchlight scan with no flags and it asks. Each answer has a flag that skips the question
next time — the picker prints them, so you only see it until you have learned the one you want.
| Mode | Reads | Flag | When |
|---|---|---|---|
| Changed files | what this branch touched, uncommitted work included | --diff | every push. Seconds, cents |
| Whole repository | every scannable file here | (default) | monthly, or on a repo you just inherited |
| A directory | one subtree | --path <dir> | reviewing one service in a monorepo |
patchlight scan --diff # changed files
patchlight scan --diff --base main # against an explicit base
patchlight scan --diff --no-neighbours # changed files only, no siblings
patchlight scan --path src/api # one subtreeWhy --diff is the one to learn
A branch scan reads only what you changed — plus the other files in the same directories, so a vulnerability that spans two files is still visible. It takes seconds, it costs cents, and it sees code you have not committed, which a server that clones your repository structurally cannot.
What happens
Local walk
Instant, no network. Walks the tree and skips node_modules, build output, lockfiles, and
binaries.
Preflight
Checks your balance and the size caps before a single byte of code is uploaded. A scan that cannot be paid for never sends anything.
Upload
A bounded snapshot of the working tree — only the text files that survived the walk.
Triage pass
How much of that is worth reading closely, summarised by weakness family.
Findings
Streamed in as the model completes each one, not batched to the end. You start reading the first finding while the rest are still being written.
All of it runs fullscreen. 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, on a tinted block with the flagged line picked out, and the suggested fix underneath.
↑↓ move · d dismiss · r resolve · u reopen · o open in $EDITOR · q quit| Key | Action |
|---|---|
↑ ↓ / k j | Move between findings |
PgUp PgDn | Move a page at a time |
g / G | Jump to the first / last finding |
d | Dismiss |
r | Resolve |
u | Reopen |
o | Open in $EDITOR at the right line |
q / Esc | Quit |
o hands the terminal to your editor and takes it back when you quit. vim, code, cursor,
subl, and zed each 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.
Reporting a finding upstream
Found something in a dependency, or in a repository that is not yours?
patchlight report <finding-id> | pbcopyPrints the finding as private-disclosure markdown on stdout — ready to paste into a project's security policy form or a GitHub advisory, whose URL is printed on stderr so the pipe stays clean.
Scan code you are authorised to scan. Findings on someone else's repository go to that project's private disclosure channel, never a public issue.
Non-interactive use
Piping or redirecting output turns off the picker, the fullscreen UI, and the triage keys. The scan still runs and still prints its findings — as one plain report.
patchlight scan --diff > scan.log
patchlight scan --diff | tee scan.logWhat leaves your machine
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.
Scans bill per token, so cost tracks how much code you send. --diff is not just faster; it is the
cheap one.