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

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

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

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

Flag	Effect
--json	Emit JSON on stdout; route info/progress lines to stderr; errors emitted as a structured envelope.
--quiet	Suppress informational output. Errors and payloads still render.
--no-color	Disable ANSI styling. Also honours the NO_COLOR env var.
--no-interactive	Refuse to block on TUI prompts; commands that need a prompt return an error instead. Implied by --json, non-TTY stdin/stdout, and any of the CI / BUILD_NUMBER / RUN_ID env vars.

Environment variables

Variable	Effect
VULNCHECK_API_TOKEN	API token, and the recommended name — shared with the VulnCheck SDKs and MCP server. Takes precedence over ~/.config/vulncheck/vulncheck.yaml; while set, auth login and auth logout refuse rather than writing a file that would be ignored.
VC_TOKEN	Legacy alias, still fully supported and taking precedence over VULNCHECK_API_TOKEN when both are set, so no existing setup changes credential. Clear both to fall back to the config file. auth status reports which is in use.
NO_COLOR	Any non-empty value disables ANSI styling.
CI / BUILD_NUMBER / RUN_ID	Any of these set implies non-interactive mode (no prompts).

Exit codes

Code	Meaning
0	Success.
1	Generic / internal error.
2	Validation failure (bad args, missing required flag, malformed request).
3	Auth failure (no token, or the server rejected the token).
4	Resource not found (HTTP 404, no such index).
5	Rate limited (HTTP 429).
6	Network failure (DNS, connection refused, timeout).
130	Cancelled by SIGINT (POSIX 128 + 2).

Error envelope

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.

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",
#  "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.

Pagination