CLI
Command-Line Interface
Run a VulnRadar scan from a terminal or a CI job and fail the build when findings cross a threshold you set. Run it with npx, no install required.
Overview
The vulnradar CLI wraps the scan API: it starts a scan, polls until it finishes, prints a summary, and exits non-zero when the finding counts go over the limits you set. That exit code is the whole point: drop it into a pipeline step and a regression fails the build.
Install
The CLI is on npm as vulnradar. npx needs no install at all, which is usually what you want in CI:
npx vulnradar scan https://example.com --max-high 0For a permanent command on your PATH:
npm i -g vulnradar
vulnradar scan https://example.com --api-key vr_live_...It needs Node 22 or newer, the same floor as the rest of the project (cli/package.json declares engines.node >=22.0.0), and has no dependencies of its own.
From source
Only needed to work on the CLI itself, or to run a change that is not released yet:
git clone https://github.com/VulnRadar/vulnradar.dev.git
cd vulnradar.dev/cli
npm install -g .Or run the entrypoint directly with node cli/vulnradar.mjs scan <url>, no install at all.
Usage
vulnradar scan <url> [options]Pass your key with --api-key or the VULNRADAR_TOKEN environment variable. Prefer the variable in CI so the key never lands in shell history or logs. --api-base has the same env form, VULNRADAR_API_BASE, so a self-hosted CI does not repeat the flag on every invocation. An explicit flag beats the variable in both cases.
Options
| Flag | What it does | Default |
|---|---|---|
| --api-key <key> | API token. Falls back to VULNRADAR_TOKEN. | env |
| --api-base <url> | API base URL, for a self-hosted instance. Falls back to VULNRADAR_API_BASE. | https://vulnradar.dev/api/v3 |
| --crawl | Crawl and scan multiple pages instead of a single URL. The cap depends on your plan (Free 25, Core 50, Pro 100, Elite 250). | off |
| --max-critical <n> | Exit non-zero if criticals exceed n. | 0 |
| --max-high <n> | Exit non-zero if highs exceed n. | 0 |
| --max-medium <n> | Exit non-zero if mediums exceed n. -1 disables the check. | -1 |
| --timeout <seconds> | Give up waiting for the scan to finish. With --crawl and no explicit --timeout it becomes 900, matching the server's crawl budget. | 300 |
| --poll-interval <s> | Seconds between status polls. | 5 |
| --json | Print the raw completed result as JSON. | off |
| -h, --help | Show usage. |
Exit codes
0 when every finding count is at or under its threshold; 1 when a threshold is exceeded or the scan errors out. That is what lets a CI job block a merge on a new critical.
CI example
Once the CLI is on the runner (see Install), a GitHub Actions step fails the build on any new critical or high:
- name: VulnRadar scan
env:
VULNRADAR_TOKEN: ${{ secrets.VULNRADAR_TOKEN }}
run: vulnradar scan https://staging.example.com --max-critical 0 --max-high 0Want a gate with nothing to install? The API docs cover a GitHub Action, a GitLab template, and a plain curl script that hit the same API.