Overview

The GitHub App reviews pull requests automatically. For everywhere else — GitLab, Bitbucket, Azure Repos, self-hosted git, or a pipeline you wrote yourself — @patchlight/sdk submits a diff for review from wherever your code lives, waits for the findings, and can fail the build on them.

It ships two things in one package:

• a TypeScript client (createClient) for programmatic use, and
• a CLI (patchlight) shaped for CI jobs: it collects the git diff, submits it, waits, prints the findings, and exits non-zero when something severe turns up.

npm install --save-dev @patchlight/sdk

Or run it without installing anything:

npx @patchlight/sdk review --wait --fail-on high

Node.js 18.17+. Zero runtime dependencies — that is the point of this package, and it stays that way.

Authentication

Create an API key in the dashboard under App → API Keys. It is shown once.

Keys belong to the workspace that was active when you created them: a key made in an organization workspace bills that organization's balance and files reviews under it; a personal key uses your personal workspace.

const client = createClient({ apiKey: process.env.PATCHLIGHT_API_KEY! });

export PATCHLIGHT_API_KEY=pl_sk_...

The client reads the key from the apiKey option; the CLI reads PATCHLIGHT_API_KEY. Store it as a masked secret in your CI provider. Keys can be revoked from the same page, and revocation takes effect within about a minute.

Base URL

The SDK talks to https://api.patchlight.dev by default. Override it with the baseUrl client option or the PATCHLIGHT_BASE_URL environment variable — useful for staging or a self-hosted deployment.

Reviews

1. You submit a unified diff — plus, optionally, the contents of the changed files, which measurably improves the review — via POST /v1/reviews.
2. The platform queues it; the diff is analysed by the same engine that powers the GitHub App.
3. You poll until the status is done, then fetch the findings.

Reviews also appear in the dashboard under a repository entry named after the repo you passed. Each one is billed in USD from the workspace's balance; submissions are rejected with 402 when the balance is too low.

Security scans

A review reads a diff. A security scan reads whole files and reports vulnerabilities with CWE classifications.

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

Because the scanner clones the repository itself, a scan through the SDK needs a repository connected through the GitHub App — the implicit repo entry created by a diff submission has no git connection and cannot be scanned. (To scan a local checkout instead, use @patchlight/cli.)

Scans bill per token, so cost scales with how much code is read rather than a flat rate. One scan per repository runs at a time.

Next