CLI Reference

Complete reference for all Vulnetix CLI commands, flags, and usage patterns.

Commands

vulnetix (root command)

Run vulnerability management tasks against the Vulnetix backend.

vulnetix

The root command runs an authentication healthcheck.

Global Flags:

vulnetix auth

Manage authentication credentials for the Vulnetix API.

vulnetix auth [login|status|verify|logout] [flags]

auth login

Authenticate with Vulnetix. Interactive by default when run in a terminal.

# Interactive login (prompts for method, org ID, key, storage)
vulnetix auth login

# Non-interactive login with Direct API Key
vulnetix auth login --org-id <UUID> --api-key <KEY> --store home

# Non-interactive login with SigV4
vulnetix auth login --org-id <UUID> --secret <KEY> --store project

Flags:

Running vulnetix auth without a subcommand also triggers login.

auth status

Show current authentication state, including the credential source, method, and masked key.

vulnetix auth status

auth verify

Verify that stored credentials can authenticate with the Vulnetix API. Does not modify credentials.

# Verify stored credentials
vulnetix auth verify

# Verify with explicit API endpoint
vulnetix auth verify --base-url https://app.vulnetix.com/api

auth logout

Remove stored credentials from all file-based stores.

vulnetix auth logout

vulnetix upload

Upload a security artifact file (SBOM, SARIF, VEX, CSAF) to Vulnetix for processing.

vulnetix upload --file <path> [flags]

The file format is auto-detected from content and extension but can be overridden. Files larger than 10MB are uploaded using chunked transfer. Authentication uses stored credentials or environment variables.

Flags:

Examples:

# Upload with stored credentials
vulnetix upload --file sbom.cdx.json

# Upload with explicit org ID
vulnetix upload --file report.sarif --org-id "123e4567-e89b-12d3-a456-426614174000"

# Override format detection
vulnetix upload --file report.json --format sarif

# JSON output for scripting
vulnetix upload --file sbom.cdx.json --json

vulnetix gha

GitHub Actions artifact management. Designed for use within GitHub Actions workflows.

gha upload

Collect and upload all artifacts from the current GitHub Actions workflow run to Vulnetix.

vulnetix gha upload [flags]

This command:

1. Collects all artifacts from the current workflow run via the GitHub API
2. Downloads and extracts each artifact
3. Uploads each file to Vulnetix using the standard upload API
4. Reports pipeline UUIDs for each uploaded file

Requires: GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_RUN_ID environment variables.

Flags:

gha status

Check the processing status of uploaded artifacts by transaction ID or artifact UUID.

vulnetix gha status --txnid <ID>
vulnetix gha status --uuid <UUID>

Flags:

vulnetix license

Analyze package licenses for conflicts, policy compliance, and risk. See the full License Command Reference for details.

vulnetix license [flags]

License analysis also runs automatically during vulnetix scan (disable with --no-licenses).

vulnetix scan

Walk the local directory tree, parse package manifests, and query the VDB for vulnerabilities — no files are uploaded. See the full Scan Command Reference for details.

vulnetix scan [flags]
vulnetix scan status <scan-id> [flags]

vulnetix sca

Run only Software Composition Analysis — vulnerability analysis on package manifests. All other features (SAST, licenses, secrets, containers, IaC) are disabled. See the SCA Command Reference.

vulnetix sca [flags]

Equivalent to vulnetix scan --evaluate-sca --no-sast --no-secrets --no-containers --no-iac --no-licenses.

vulnetix sast

Run only Static Application Security Testing. All other features are disabled. See the SAST Command Reference.

vulnetix sast [flags]

Equivalent to vulnetix scan --evaluate-sast --no-sca --no-secrets --no-containers --no-iac --no-licenses.

vulnetix secrets

Run only secret detection — identifies hardcoded credentials, API keys, and tokens. All other features are disabled. See the Secrets Command Reference.

vulnetix secrets [flags]

Equivalent to vulnetix scan --evaluate-secrets --no-sast --no-sca --no-containers --no-iac --no-licenses.

vulnetix containers

Run only container file analysis — checks Dockerfiles and Containerfiles. All other features are disabled. See the Containers Command Reference.

vulnetix containers [flags]

Equivalent to vulnetix scan --enable-containers --no-sast --no-sca --no-secrets --no-iac --no-licenses.

vulnetix iac

Run only Infrastructure as Code analysis — checks Terraform HCL and Nix files. All other features are disabled. See the IaC Command Reference.

vulnetix iac [flags]

Equivalent to vulnetix scan --evaluate-iac --no-sast --no-sca --no-secrets --no-containers --no-licenses.

vulnetix triage

Fetch vulnerability alerts from external providers (e.g. GitHub Dependabot) and enrich them with remediation intelligence from the Vulnetix VDB.

vulnetix triage [flags]
vulnetix triage status [flags]

Supported providers: github (Dependabot alerts via the gh CLI)

Flags:

For each alert the triage command fetches:

• A context-aware remediation plan (upgrade path, verification steps)
• Fix data from registry, distribution, and upstream source in parallel

Subcommands:

triage status

Verify that provider CLI tools are installed, authenticated, and functional.

vulnetix triage status [--format text|json]

Flags:

Examples:

# Interactive TUI (default)
vulnetix triage

# Triage a specific repository
vulnetix triage --repo owner/repo

# Include dismissed alerts, output as JSON
vulnetix triage --all --format json

# Check GitHub CLI auth and repo detection
vulnetix triage status

# Check status as JSON
vulnetix triage status --format json

Prerequisites: The github provider requires the gh CLI to be installed and authenticated (gh auth login).

vulnetix vdb

Interact with the Vulnetix Vulnerability Database (VDB) API. See the full VDB Command Reference for all subcommands and detailed usage.

vulnetix vdb <subcommand> [flags]

Tree-sitter reachability

vulnetix vdb vuln and the remediation flows automatically perform tree-sitter reachability analysis against your project, recording exactly which files (and line ranges) match the vulnerable pattern. Control with --reachability=direct|transitive|both|off (default both). See the Reachability Analysis section for the full feature overview, Languages for the 17 bundled grammars, and Internals for how the CGo cross-compile is structured.

vulnetix version

Print the version number of Vulnetix CLI.

vulnetix version [flags]

Also checks for available updates and prints a notice if a newer version exists.

Flags:

Examples:

# Full version info (with update check)
vulnetix version

# Just the version number, e.g. for scripting
vulnetix version --short

vulnetix update

Update the Vulnetix CLI to the latest release from GitHub.

vulnetix update

Checks the GitHub Releases API for the latest version, then downloads and replaces the current binary in-place. Binaries built from source (via go build or make dev) are not updated — use your build toolchain instead.

Behavior:

• If already up to date: prints Already up to date (vX.Y.Z).
• If a newer version is available: prints the upgrade path and performs the in-place update
• If built from source: exits with an error indicating that go build should be used

Examples:

# Check for and apply the latest update
vulnetix update

vulnetix triage

Triage vulnerability alerts from multiple providers (e.g. GitHub Dependabot) with integrated remediation intelligence from the Vulnetix Vulnerability Database.

vulnetix triage [flags]
vulnetix triage status      # Check provider CLI health

The triage command fetches vulnerability alerts from external providers, enriches each alert with VDB data (remediation plans, fix availability across registry/distribution/source), and presents them in an interactive TUI or text/JSON output.

Flags:

Examples:

# Interactive TUI with auto-detected repo
vulnetix triage

# Specify a repo and include dismissed alerts
vulnetix triage --repo owner/repo --all

# Non-interactive text output
vulnetix triage --format text

# JSON output for scripting
vulnetix triage --repo owner/repo --format json

# Check provider CLI health
vulnetix triage status

triage status

Verify that provider CLI tools (e.g. gh) are installed, authenticated, and can detect the current repository.

# Text output (default)
vulnetix triage status

# JSON output for scripting
vulnetix triage status --format json

Flags:

Output (text):

  GitHub CLI Status
──────────────────────────────────────────

  ✔ gh binary   : /usr/bin/gh
  ✔ authenticated: octocat
     Host         : github.com
     Token source : OAuth Token
     Token scopes : repo, workflow
  ✔ repo detected : owner/repo

vulnetix completion

Generate shell autocompletion scripts.

vulnetix completion [bash|zsh|fish|powershell]

Authentication

Vulnetix CLI supports two authentication methods:

Direct API Key

Uses VULNETIX_API_KEY and VULNETIX_ORG_ID environment variables, or stored credentials with --method apikey.

SigV4

Uses VVD_ORG and VVD_SECRET environment variables, or stored credentials with --method sigv4. SigV4 authenticates via a JWT token exchange with the VDB API.

Credential Storage

Credentials are stored as JSON in one of two locations:

Credential Precedence

The CLI loads credentials in this order (first match wins):

1. CLI flags: --org-id + --api-key or --secret
2. Environment variables: VULNETIX_API_KEY + VULNETIX_ORG_ID (Direct API Key)
3. Environment variables: VVD_ORG + VVD_SECRET (SigV4)
4. Project dotfile: .vulnetix/credentials.json
5. Home directory: ~/.vulnetix/credentials.json

Global Flags

These flags are available on the root command and inherited by subcommands:

Environment Variables

Exit Codes

Common Usage Patterns

Basic Usage

# Run authentication healthcheck
vulnetix

Artifact Upload

# Upload an SBOM
vulnetix upload --file sbom.cdx.json

# Upload SARIF from a scanner
semgrep --sarif > results.sarif && vulnetix upload --file results.sarif

# Upload via the upload command with format override
vulnetix upload --file report.json --format sarif --json

CI/CD Integration

# GitHub Actions
vulnetix gha upload --org-id "$VULNETIX_ORG_ID"

# GitLab CI
vulnetix upload --file results.sarif

# Jenkins
vulnetix upload --file results.sarif