CLI
Guides
Scanverra CLI
Scan any codebase from your terminal or CI pipeline with @scanverra/cli. The scan runs on your machine and only the findings are sent to Scanverra.
Quick start
Install nothing globally, or run npm i -g @scanverra/cli for a permanent scanverra command.
npx @scanverra/cli login # paste an API key from Dashboard > API keys npx @scanverra/cli scan .
How it works
Always up to date
You always run the latest checks, no separate CLI version to track or upgrade by hand.
Same engine as the dashboard
Results match what you would see from a scan started in Scanverra, wherever you run it.
Scans locally
Your source files are read on your own machine. By default, only the findings, not file contents or matched code lines, are sent to Scanverra.
Shows up in your dashboard
Each scan gets an AI-written summary and a link, the same result page as a scan started from the dashboard.
Commands
| Command | Description |
|---|---|
scanverra login | Verify and save your API key |
scanverra logout | Remove the saved key |
scanverra whoami | Show the account and plan behind the key |
scanverra scan [path] | Scan a folder (default: current folder), print the results, upload them |
scanverra audit <url> | Audit a live website's speed; with --budget, fail when it breaks a saved performance budget |
Common options
| Option | Description |
|---|---|
--json / --sarif | Machine-readable output. SARIF works with GitHub code scanning and Sonar import |
--fail-on <severity> | Exit with a failure if a finding at or above this severity exists (default: high) |
--fail-on-new, --baseline-branch <name>, --baseline-commit <sha> | Fail only when this scan adds a critical or high issue compared with the previous uploaded scan (the new-code gate, for pull requests). Add --baseline-branch main to compare with the target branch. If that branch has never been scanned, every critical or high issue counts as new. The scan of the commit your branch started from is used when known (from git merge-base, or --baseline-commit <sha>), so fixes that landed on the target branch later don't count against you. Replaces --fail-on; needs an upload |
--category <list> | Only include security, dependency, iac or quality findings |
--exclude <glob> | Skip matching paths. A .scanverraignore file works the same way |
--no-upload | Scan only, do not send results to Scanverra |
--include-code | Also upload the matched source line of each finding (off by default) |
--offline | Use the cached rules with no network calls |
--api-key, --api-url | Override the credentials or server, useful in CI |
--save-budget <file> | Audit: save a budget from this run (limits with headroom + allowed third parties) |
--budget <file> | Audit: check against a saved budget; exit 1 on any violation |
What is uploaded
File paths, line numbers, rule IDs, titles, descriptions, fix suggestions, severities, dependency names and versions, and the project name, branch, commit and PR number.
File contents, and the matched source line of each finding. Secret findings never carry the secret value itself. Pass --include-code if you want matched lines shown in the dashboard.
How files are chosen
- Inside a git repository, tracked and untracked files are used and .gitignore is respected. Outside git, common build and dependency folders are skipped.
- A .scanverraignore file (one glob per line) and repeatable --exclude flags add more exclusions.
- Suppress a single finding with a scanverra-ignore or nosec comment on the line above it.
Exit codes
| 0 | Success, and no finding reached the --fail-on threshold |
| 1 | A finding reached the threshold, the quality gate failed with --fail-on-gate, or the scan added a critical or high issue with --fail-on-new |
| 2 | Usage error, the server rejected the key or plan, or a vulnerability database couldn't be reached so the result couldn't be verified (rerun) |
Using it in CI
Store the API key as a secret the same way as any other Scanverra CI integration, and cache the rules folder so a fresh runner does not re-download them on every run.
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with: { node-version: 24 }
- run: npx @scanverra/cli scan . --fail-on high
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}Cache the rules between runs
- uses: actions/cache@v4
with:
path: ~/.cache/scanverra
key: scanverra-rules-${{ github.run_id }}
restore-keys: scanverra-rules-Performance budget for your website
Commit a budget from a good deploy. Every later run fails the build when the page gets slower or heavier, or a new third party appears.
# once, from a good deploy:
scanverra audit https://staging.example.com --save-budget perf-budget.json
# in CI, after deploying a preview:
- run: npx scanverra audit "$PREVIEW_URL" --budget perf-budget.json
env:
SCANVERRA_API_KEY: ${{ secrets.SCANVERRA_API_KEY }}Troubleshooting
| Message | What to do |
|---|---|
Not logged in | Run scanverra login, or set SCANVERRA_API_KEY |
API key was rejected | The key is wrong or was revoked. Create a new one under API Keys |
You have reached your free scan limit | You've used this month's free Repo Scanner scans. Scan with --no-upload, wait until next month, or upgrade. |
Daily limit for downloading the scanner rules reached | Cache the rules folder in CI, see above |
No scannable files found | Check the path and your .gitignore or .scanverraignore |
Ready to scan from the terminal?
Generate an API key, then run your first scan in under a minute.