CLI — npx pulllight scan

Run PullLight AI review against your local git diff before opening a PR. Zero install, severity-colored output, exit code 1 on critical/high so you can wire it into pre-commit hooks or CI.

Node.js ≥ 18 no heavy deps exit-code aware pre-commit ready

Quickstart

1. Get an API token

Generate a token at /settings/api-tokens. Tokens start with plk_.

2. Run your first scan

Stage some changes, then:

$ npx pulllight scan

On first run, you'll be prompted to paste your token. It's saved to ~/.config/pulllight/config.json for future runs.

Set PULLLIGHT_API_TOKEN=plk_... as an environment variable to skip the interactive prompt — useful in CI and pre-commit hooks.

3. Compare against a branch

$ npx pulllight scan -b main

Runs git diff main...HEAD and sends the full range to Claude.

Flags reference

FLAG DESCRIPTION
-b, --base <ref> Compare against a base branch or commit SHA. Defaults to staged + unstaged changes.
--severity-floor <level> Drop findings below this severity. Values: low | medium | high | critical.
--ignore <glob> Exclude files matching this pattern from analysis. Repeatable. Example: --ignore 'vendor/**'
--json Output raw JSON to stdout. Useful for CI pipelines and scripting. Honors exit codes.

Exit codes

The exit code lets you gate on severity without parsing output.

0
No critical or high findings (low/medium findings may still be present)
1
One or more critical or high severity findings found

Pre-commit hook recipe

Block commits when high-severity findings exist. Save as .git/hooks/pre-commit and chmod +x it:

#!/bin/sh
# Run PullLight on staged changes. Exit 1 on critical/high findings.
export PULLLIGHT_API_TOKEN=plk_your_token_here
npx --yes pulllight scan --severity-floor high
if [ $? -ne 0 ]; then
  echo "PullLight: critical/high findings — fix before committing."
  exit 1
fi

Tip: Add --ignore 'vendor/**' --ignore '*.generated.*' to skip auto-generated files.

Husky integration

If you use Husky for Git hooks:

1. Install Husky

npx husky init

2. Add the pre-commit hook

echo 'PULLLIGHT_API_TOKEN=$PULLLIGHT_API_TOKEN npx pulllight scan --severity-floor high' > .husky/pre-commit

3. Set the token in your environment

Add to your shell profile (~/.zshrc, ~/.bashrc) or CI secrets:

export PULLLIGHT_API_TOKEN=plk_your_token_here

Store the token in your CI secrets manager (GitHub Actions: secrets.PULLLIGHT_API_TOKEN) — never hard-code it in committed files.

GitHub Actions example

Run PullLight on every push as a non-blocking advisory check, or gate merges on it with --severity-floor high.

# .github/workflows/pulllight.yml
name: PullLight AI Review
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # needed for git diff against base
      - name: Run PullLight
        env:
          PULLLIGHT_API_TOKEN: ${{ secrets.PULLLIGHT_API_TOKEN }}
        run: npx --yes pulllight scan -b origin/main --severity-floor high

JSON mode

Pass --json to get machine-readable output. The exit code still reflects severity.

npx pulllight scan --json | jq '.findings[] | select(.severity == "high")'

Response shape

{
  "findings": [
    {
      "file": "src/auth.js",
      "line": 42,
      "severity": "high",
      "category": "auth",
      "body": "Missing permission check before token refresh...",
      "suggested_fix": null
    }
  ],
  "meta": {
    "findings_count": 1,
    "severity_max": "high",
    "exit_code": 1,
    "model": "claude-sonnet-4-5",
    "input_tokens": 1240,
    "output_tokens": 188
  }
}

Token management

API tokens are managed at /settings/api-tokens. Each token is scoped to your installation and can be revoked at any time.

  • Tokens are shown exactly once on creation — store them in a password manager or secrets vault
  • Rate limit: 60 requests per minute per token
  • Generate separate tokens for local dev vs CI pipelines so you can revoke CI access independently

To update your locally stored token:

npx pulllight config set-token