gem-hunter

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

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

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.

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

Open PowerShell and run:

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

To enable tab completion, dot-source the bundled script from your PowerShell profile:

Add-Content -Path $PROFILE -Value ". '$env:LOCALAPPDATA\Programs\vulncheck\share\powershell\vulncheck.ps1'"

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

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.

• Run vulncheck auth login to authenticate with your VulnCheck account.
• Alternatively vulncheck will respect the VULNCHECK_API_TOKEN environment variable — the same name used by the VulnCheck SDKs and MCP server. The legacy VC_TOKEN also still works, and takes precedence when both are set.
• vulncheck auth by itself will show other options like checking your status and logging out.

Either environment variable wins over the saved config file. Because of that, auth login and auth logout refuse while one is set — otherwise they would report success having changed nothing that takes effect. Run vulncheck auth status to see which source, and which variable, the active token came from.

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

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

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

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. hint is optional remediation context, present only when the message alone isn't actionable (e.g. naming the variable that supplied a rejected token). Rendered on stderr as hint: ... outside --json mode.

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",
#  "token_env_var": "VC_TOKEN", "user": "...", "email": "..."}
# Exit 0 even when authenticated=false — agents dispatch on the bool.
# token_env_var names which variable supplied the token when token_source is
# "env"; omitted otherwise. Set when authenticated=false too, so a rejected
# token can be traced to the variable holding it.
# token_shadowed: true is added when an environment token is overriding a
# *different* token saved in vulncheck.yaml — the usual cause of "I logged
# in but nothing changed". Omitted otherwise, so the CI shape (env token
# only, no config file) never reports shadowing.

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.

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

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"}
]

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.

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.

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
• advisory — query v4 advisories in CVE Record Format 5.2
• nvd — query the NVD API 2.0 compatible endpoints
• backup — download or fetch a signed URL for an index or advisory-feed 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

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

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.

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

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

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.

vulncheck advisory feeds [search]                      # GET /v4/advisory/list
vulncheck advisory list [--full] [--all] [query flags] # GET /v4/advisory
vulncheck advisory browse [--full] [query flags]

Every record is CVE Record Format 5.2, and there is one record per feed per CVE.

At least one filter is required; see advisory list --help for the set (--feed, --cve, --vendor, --purl, --updated-after, …) and advisory feeds for --feed values. --limit caps at 100 and --page × --limit at 10,000 — page past that with --start-cursor and --cursor, or --all to walk it in one call (which buffers every record, so prefer cursors on the largest feeds). browse runs an interactive viewport.

vulncheck nvd cves       [--full] [query flags]   # GET /rest/json/cves/2.0
vulncheck nvd cvehistory [--full] [query flags]   # GET /rest/json/cvehistory/2.0
vulncheck nvd cpes       [--full] [query flags]   # GET /rest/json/cpes/2.0
vulncheck nvd cpematch   [--full] [query flags]   # GET /rest/json/cpematch/2.0
vulncheck nvd source     [--full] [query flags]   # GET /rest/json/source/2.0

These mirror the NVD API 2.0: each flag is an NVD query parameter in kebab-case (--cve-id is cveId, --last-mod-start-date is lastModStartDate), its value is sent unchanged, and the API validates it. They work with any VulnCheck API token, including community. Output is the endpoint's records (vulnerabilities, cveChanges, products, matchStrings or sources); --full returns the whole NVD response. Each command makes one request: to page, pass --cursor "" for the first page and then each response's nextCursor, or --start-index (the only paging on source).

vulncheck nvd cves --cve-id CVE-2021-44228 --json
vulncheck nvd cves --has-kev --results-per-page 100 --cursor "" --full --json
vulncheck nvd cvehistory --event-name "CVE Modified" --change-start-date 2026-09-01T00:00:00.000 --change-end-date 2026-10-01T00:00:00.000 --json

vulncheck backup list                       # indices with a backup available
vulncheck backup url <index>                # signed temporary URL only
vulncheck backup download <index>           # download the archive

vulncheck backup advisory list              # GET /v4/backup
vulncheck backup advisory url <feed>        # GET /v4/backup/{feed}
vulncheck backup advisory download <feed>

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

The advisory subcommands are a different corpus, not a newer version of the same archives, and most feed names are also index names — so the same argument usually addresses both. A v3 zip holds that feed's native records — for sigmahq-sigma-rules that includes the Sigma rule itself and its ATT&CK techniques — while the v4 zip holds CVE 5.2 records, one per CVE, dropping both those fields and every advisory with no CVE attached. A feed whose advisories are mostly not CVE-keyed can shrink to a fraction of its v3 record count. The v4 archive is a single <feed>.jsonl inside the zip, and its lists are parquet-shaped ({"list":[{"element":…}]}), so it is not a bulk copy of advisory list --json. The v4 object key carries no timestamp, so repeat downloads overwrite rather than accumulate — the command warns when it does. url/download --json carry corpus and format fields, because a bare abbott.zip on disk records nothing about which corpus produced it, and a url field so jq -r .url works against both.

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.

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.

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.

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

Passive-DNS list membership. Batch input supported.

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

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

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

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

vulncheck version [--json]

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

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.