cli

The VulnCheck CLI

vulncheck is access to the VulnCheck API on the command line. It brings index browsing, backup management, and vulnerability scanning to the terminal.

Installation

Provided install scripts

You can easily install vulncheck using an install script. Choose the script and method that matches your operating system:

macOS and Linux

Open a terminal and run:

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash

This will prompt you to choose between system-wide installation (requires sudo) or local user installation.

[!NOTE] The install script also supports non-interactive installation options:

• --sudo for system-wide installation without prompts
• --non-sudo for local user installation without prompts
• --help or -h to see all available options

curl -sSL https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.sh | bash -s -- --help

Windows

Open PowerShell and run:

iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/vulncheck-oss/cli/main/install.ps1'))

vulncheck binaries are also available for MacOS, Linux, and Windows. You can download precompiled binaries from our releases page

Verify the installation

Once installed, confirm the binary prints the desired version:

vulncheck version

You should see the version, build date, and changelog URL. If you get "command not found", reopen your shell so the new PATH is picked up, then try again.

Configuration

• Run vulncheck auth login to authenticate with your VulnCheck account.
• Alternatively vulncheck will respect the VC_TOKEN environment variable.
• vulncheck auth by itself will show other options like checking your status and logging out.

Agentic / scripted usage

The CLI is designed to be safe to drive from scripts and AI agents. This section is the contract — the surfaces below are intended to remain stable across releases (additions are not breaking changes; renames / removals are).

Global flags

Environment variables

Exit codes

Error envelope

In --json mode, errors are emitted to stdout as:

{
  "schema_version": 1,
  "error": {
    "code": "auth_required",
    "message": "...",
    "http_status": 401
  }
}

code is one of: internal, validation, auth_required, auth_invalid, not_found, rate_limited, network, bad_request, cancelled. http_status is omitted for non-HTTP errors.

Probe commands

Use these to inspect the CLI itself before dispatching work:

vulncheck version --json
# {"schema_version": 1, "version": "...", "build_date": "...", "changelog_url": "..."}

vulncheck auth status --json
# {"schema_version": 1, "authenticated": true, "token_source": "env", "user": "...", "email": "..."}
# Exit 0 even when authenticated=false — agents dispatch on the bool.

vulncheck commands
# {"schema_version": 1, "root": {"name":"vulncheck", "subcommands":[...]}, ...}
# Machine-readable dump of the whole command tree — every subcommand,
# every flag (with type + default + usage), aliases, deprecation. Use
# this instead of parsing --help. Auth is not required.

Pagination

vulncheck token list --json --limit 10 --page 2
vulncheck token list --json --all       # auto-paginate, single combined array
vulncheck index list <index> --json --all

Batch input

purl, cpe, tag, pdns accept multiple inputs via positional args, stdin (when piped), or --from-file <path>. Blank lines and #-prefixed comments in the file are ignored. Batch mode requires --json.

# Stdin
cat purls.txt | vulncheck purl --json

# File
vulncheck cpe --from-file ./cpes.txt --json

The batch envelope is a stable array, one row per input, in input order:

[
  {"input": "pkg:npm/lodash@4.0.0", "data": { ... }},
  {"input": "pkg:bad/string", "error": "no result returned for this purl"}
]

Cancellation

SIGINT / SIGTERM cancel in-flight HTTP requests cleanly via context propagation. Long-running ops (scan, offline sync, backup download) honour cancellation; partial files are removed on the way out where applicable.

JSON output discipline

When --json is set:

• stdout carries only the JSON payload (or the error envelope above).
• stderr carries every info line, progress bar, spinner, prompt, and warning.
• TUI elements (bubbletea, huh prompts) are automatically suppressed.

This means vulncheck <cmd> --json | jq always works — no tail/sed cleanup needed.

Available commands

Every command below accepts the global flags (--json, --quiet, --no-color, --no-interactive, --help/-h). Per-command flag tables list only what is specific to that command.

• auth — log in / out, check status
• token — API token management
• indices — list or browse the catalogue of indices
• index — query one index
• backup — download or fetch a signed URL for an index backup
• cpe — look up CVEs for a CPE (single or batch)
• purl — look up CVEs for a PURL (single or batch)
• tag — look up IP-intelligence tag membership
• pdns — look up passive-DNS list membership
• rule — look up initial-access-intelligence rules
• scan — scan a directory (SBOM + vulnerability lookup)
• offline — sync indices locally and query them without hitting the API
• version — print the CLI version
• upgrade — update the CLI in place

auth

vulncheck auth login
vulncheck auth logout
vulncheck auth status [--json]

login walks you through a browser or paste-token flow — refuses when --no-interactive. status --json calls /me to actually verify the token; the payload always has .authenticated: bool and exits 0 regardless (see Probe commands).

token

vulncheck token list [--limit N] [--page N] [--all]
vulncheck token create <label>
vulncheck token remove <id>
vulncheck token browse

list --json --all auto-paginates and returns one combined JSON array.

create --json returns {schema_version, id, label, token_on_stderr: true} and prints the actual secret on a single line to stderr. That way a pipeline like vulncheck token create ci-runner --json > token.json never captures the secret in the JSON file. Pass --allow-token-on-stdout if you want the token embedded in the JSON payload instead ({... "token": "vc_..."}) — you're taking responsibility for the redirection.

browse is interactive; it refuses with exit 2 under --no-interactive.

indices

vulncheck indices list [<search>]
vulncheck indices browse [<search>]

Lists (or interactively browses) the catalogue of available indices. list accepts a fuzzy search term.

index

vulncheck index list <index> [--full] [--all] [query flags]
vulncheck index browse <index> [query flags]

list --all walks next_cursor end-to-end and emits one combined array. browse runs an interactive viewport; under --json (or --no-interactive) it falls back to list output. Query flags come from the index's schema (--cve, --alias, --limit, --cursor, etc.); see the API docs for the full set.

backup

vulncheck backup url <index>       # signed temporary URL only
vulncheck backup download <index>  # download the archive

download picks the bubbletea progress bar for TTYs and a plain SIGINT-safe streaming download (writing to <name>.part and renaming on success) for headless callers. url --json returns {filename, sha256, date_added, url}.

cpe

vulncheck cpe <cpe>
vulncheck cpe --from-file cpes.txt --json
echo cpe:2.3:… | vulncheck cpe --json

Batch mode (multiple positional args, --from-file, or piped stdin) requires --json and returns the stable batch envelope.

purl

vulncheck purl <purl>
vulncheck purl --from-file purls.txt --json

Same batch semantics as cpe. Batch requests are sent as a single /v3/purls POST rather than N GETs.

tag

vulncheck tag <tag-name>
vulncheck tag --from-file tags.txt --json

Returns the newline-split list of matches for the given IP-intelligence tag. Batch input supported.

pdns

vulncheck pdns <list-name>
vulncheck pdns --from-file lists.txt --json

Passive-DNS list membership. Batch input supported.

rule

vulncheck rule <rule-name> [--table]

Look up an initial-access-intelligence rule. --table renders single-column table output; --json (global) supersedes.

scan

vulncheck scan <path> [flags]
vulncheck scan --sbom-input-file <file> --json

Generates an SBOM for <path>, extracts PURLs, then either calls the vulncheck API (default) or queries local offline indices.

The progress TUI is auto-suppressed whenever the renderer can't safely draw it (--json, --no-interactive, non-TTY, CI).

offline

vulncheck offline sync   [--add <name>|--remove <name>|--purge|--force|--choose] [--json]
vulncheck offline status [--json]
vulncheck offline purl   <purl> [--json]
vulncheck offline cpe    <cpe>  [--json] [--stats]
vulncheck offline ipintel <3d|10d|30d> [--country=...] [--asn=...] [--cidr=...] [--json]

Local queries against synced indices. sync --json returns {schema_version, action, selected, elapsed_seconds}; status --json returns the cached-index array. Under --no-interactive the sync command refuses without an explicit --add / --remove / --purge (no picker prompt).

version

vulncheck version [--json]

--json returns {schema_version, version, build_date, changelog_url} — the canonical probe for agents.

upgrade

vulncheck upgrade status
vulncheck upgrade latest [--force]
vulncheck upgrade --version X.X.X

• upgrade status — check whether a newer release is available.
• upgrade latest — install the newest release. --force reinstalls the current version.
• upgrade --version X.X.X — install a specific version.

[!TIP] Looking to plug this into your Github Repository? Check out our own Action