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 --org-id <UUID> [--task <task>] [flags]

The root command runs one of several task modes (--org-id required for non-info tasks):

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, secret, storage)
vulnetix auth login

# Non-interactive login with Direct API Key
vulnetix auth login --method apikey --org-id <UUID> --secret <KEY> --store home

# Non-interactive login with SigV4
vulnetix auth login --method sigv4 --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 --org-id <UUID> [flags]

This command:

1. Collects all artifacts from the current workflow run via the GitHub API
2. Gathers GitHub Actions metadata from environment variables
3. Initiates a transaction with the Vulnetix API
4. Uploads each artifact with the transaction ID
5. Reports the transaction ID and artifact UUIDs

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 --org-id <UUID> --txnid <ID>
vulnetix gha status --org-id <UUID> --uuid <UUID>

Flags:

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]

vulnetix version

Print the version number of Vulnetix CLI.

vulnetix version

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. Environment variables: VULNETIX_API_KEY + VULNETIX_ORG_ID (Direct API Key)
2. Environment variables: VVD_ORG + VVD_SECRET (SigV4)
3. Project dotfile: .vulnetix/credentials.json
4. Home directory: ~/.vulnetix/credentials.json

Global Flags

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

Environment Variables

Tools Configuration

The --tools flag accepts a YAML array of tool configurations:

TOOLS_CONFIG='[
  {
    "category": "SAST",
    "tool_name": "semgrep",
    "artifact_name": "sast-results",
    "format": "SARIF"
  },
  {
    "category": "SCA",
    "tool_name": "trivy",
    "artifact_name": "dependency-scan",
    "format": "SARIF"
  }
]'

vulnetix --org-id "your-org-id" --task scan --tools "${TOOLS_CONFIG}"

Tool Configuration Schema

Exit Codes

Common Usage Patterns

Basic Usage

# Process vulnerability data
vulnetix --org-id "your-org-id"

# With project context
vulnetix --org-id "your-org-id" \
  --project-name "web-app" \
  --team-name "frontend-team" \
  --tags '["Public", "Crown Jewels"]'

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 --org-id "$VULNETIX_ORG_ID" --task scan

# GitLab CI
vulnetix --org-id "$VULNETIX_ORG_ID" --task scan \
  --project-name "$CI_PROJECT_NAME"

# Jenkins
vulnetix --org-id "$VULNETIX_ORG_ID" --task scan \
  --project-name "$JOB_NAME"