Skip to main content

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:

bash
npx vulnradar scan https://example.com --max-high 0

For a permanent command on your PATH:

bash
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:

bash
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

text
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

FlagWhat it doesDefault
--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
--crawlCrawl 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
--jsonPrint the raw completed result as JSON.off
-h, --helpShow 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:

YAML
- name: VulnRadar scan
  env:
    VULNRADAR_TOKEN: ${{ secrets.VULNRADAR_TOKEN }}
  run: vulnradar scan https://staging.example.com --max-critical 0 --max-high 0

Want 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.

Command-Line Scanning and CI Gating | VulnRadar