CLI Reference

Table of contents

vekt scan

Scan a directory for all supported lockfiles and check every package against the threat intel database.

vekt scan [PATH] [OPTIONS]

Arguments:

Argument Description Default
PATH Directory to scan . (current directory)

Options:

Flag Description
--json Output results as JSON instead of human-readable text
--malicious-only Report only confirmed malicious packages; suppress vulnerability findings
--quiet, -q Suppress all output when no findings are detected. Useful for cron jobs and scripts.

Behavior:

  • Walks the directory tree recursively
  • Skips node_modules, target, .venv, __pycache__, vendor, and .git directories
  • Skips hidden directories (names starting with .)
  • Deduplicates packages across multiple lockfiles before querying -- one query per unique package-version-ecosystem triple
  • Prints findings to stdout; progress messages to stderr

Examples:

# Scan current directory
vekt scan .

# Scan a specific project
vekt scan /path/to/project

# JSON output for downstream processing
vekt scan . --json | jq '.[] | select(.findings | length > 0)'

# Only show malicious packages (fastest signal in CI)
vekt scan . --malicious-only

# Silent on clean scan (for cron/scripts)
vekt scan . --quiet && echo "clean"

JSON output format:

[
  {
    "lockfile": "./package-lock.json",
    "type": "package-lock.json",
    "ecosystem": "npm",
    "packages_scanned": 312,
    "findings": [
      {
        "package": "lodash",
        "version": "4.17.15",
        "ecosystem": "npm",
        "malicious": false,
        "security_holder": false,
        "vulns": [
          {
            "id": "GHSA-jf85-cpcp-j695",
            "summary": "Prototype Pollution in lodash",
            "threat_level": "Vulnerability",
            "aliases": ["CVE-2019-10744"],
            "url": "https://osv.dev/vulnerability/GHSA-jf85-cpcp-j695"
          }
        ]
      }
    ]
  }
]

vekt check

Check a single lockfile against the threat intel database.

vekt check <LOCKFILE> [OPTIONS]

Arguments:

Argument Description
LOCKFILE Path to a lockfile

The lockfile type is inferred from the filename. The filename must exactly match a supported format (see supported lockfiles).

Options:

Flag Description
--json Output results as JSON
--malicious-only Report only confirmed malicious packages

Examples:

vekt check package-lock.json
vekt check /path/to/project/Cargo.lock
vekt check requirements.txt --json
vekt check Gemfile.lock --malicious-only

vekt list

List all supported lockfiles found in a directory without running any queries.

vekt list [PATH]

Arguments:

Argument Description Default
PATH Directory to search . (current directory)

Example:

vekt list .

Output:

DETECTED: 4 lockfiles found in .:

  npm (2)
    ./package-lock.json
    ./frontend/package-lock.json
  PyPI (1)
    ./requirements.txt
  crates.io (1)
    ./Cargo.lock

Use this to verify Vekt detects the lockfiles in your project before running a full scan.

vekt ci

Coming soon.

Opinionated CI mode. Scans the current directory and exits with a non-zero code if findings at or above the specified severity are detected.

vekt ci [OPTIONS]

Options:

Flag Description Default
--fail-on <LEVEL> Minimum severity to fail the build high
--sarif Output SARIF format for GitHub Advanced Security
--badge Generate a README badge SVG

Severity levels: malicious, critical, high, medium, low

The malicious level only fails on confirmed malicious packages, not vulnerabilities.

See the CI/CD integration guide for full examples.

vekt auth

Manage API key authentication.

vekt auth set

Store an API key for use by subsequent commands.

vekt auth set <API_KEY>

The key is written to the config file at ~/.config/vekt/config.toml. It is not printed to the terminal after being set.

vekt auth set vkt_live_xxxxxxxxxxxxxxxxxxxx

vekt auth status

Display authentication status, plan, and usage.

vekt auth status

Output:

Authenticated as: [email protected]
Plan: Pro (5,000 scans/mo)
Used this period: 1,247 scans
Remaining: 3,753 scans
Resets: 2026-04-01

vekt auth clear

Remove the stored API key.

vekt auth clear

vekt ignore

Manage the .vektignore file to suppress findings for known false positives or accepted risks.

vekt ignore add

Add a package to the ignore list.

vekt ignore add <PACKAGE> --ecosystem <ECOSYSTEM> [--reason <REASON>]

# Ignore a specific version
vekt ignore add [email protected] --ecosystem npm --reason "Not exploitable in our context, upgrading next sprint"

# Ignore all versions
vekt ignore add lodash --ecosystem npm --reason "Internal package, no external exposure"

vekt ignore list

Print all entries in the current .vektignore file.

vekt ignore list

vekt ignore remove

Remove an entry from the ignore list.

vekt ignore remove <PACKAGE> --ecosystem <ECOSYSTEM>

vekt report

Coming soon.

Generate a formatted security report from the most recent scan.

vekt report [OPTIONS]

Planned output formats: Markdown, HTML, PDF, JSON.

vekt diff

Coming soon.

Compare findings between two lockfile states (e.g., before and after a PR).

vekt diff <BEFORE> <AFTER>

Useful for pre-commit hooks and PR checks that should only fail on newly introduced findings.

Exit codes

Code Meaning
0 Scan completed with no findings
1 Scan completed and findings were detected
2 Scan error (parse failure, network error, invalid arguments)

Scripts and CI pipelines should treat exit code 1 as an actionable signal (findings present) and exit code 2 as an infrastructure or configuration problem.

Environment variables

Variable Description
VEKT_API_KEY API key. Takes precedence over the key stored in the config file.
VEKT_CONFIG Path to a custom config file. Default: ~/.config/vekt/config.toml
NO_COLOR Set to any value to disable ANSI color output

Configuration file

The config file lives at ~/.config/vekt/config.toml by default. You can override the path with VEKT_CONFIG.

[auth]
api_key = "vkt_live_xxxxxxxxxxxxxxxxxxxx"

[scan]
# Directories to skip during recursive scan (in addition to built-in exclusions)
exclude = ["vendor", "third_party", "fixtures"]

[output]
# Default output format: "human" or "json"
format = "human"
# Disable color output
no_color = false

[severity]
# Minimum severity to report: "malicious", "critical", "high", "medium", "low", "info"
minimum = "low"

Project-level config can be placed in .vektrc or vekt.toml at the project root. Project config is merged with user config; project values take precedence.

# vekt.toml (project root)
[scan]
exclude = ["tests/fixtures"]

[severity]
minimum = "high"

.vektignore file

The .vektignore file suppresses specific findings. Place it in the project root or any parent directory.

Each entry specifies a package, optionally scoped to a version and/or advisory ID:

# Ignore all findings for a package in an ecosystem
npm:lodash

# Ignore a specific version
npm:[email protected]

# Ignore a specific advisory for a package
npm:lodash GHSA-jf85-cpcp-j695

# Ignore a specific advisory for a specific version
npm:[email protected] GHSA-jf85-cpcp-j695

# Comments are supported
# PyPI packages
pypi:[email protected] GHSA-xxxx-yyyy-zzzz

Supported ecosystem prefixes: npm, pypi, crates, go, rubygems, packagist, nuget, pub, swift, hex, hackage, cran.

Entries in .vektignore are reflected in JSON output -- suppressed findings appear with "ignored": true rather than being omitted entirely.