Configuration

Configuration

vexes uses a layered configuration system: defaults < user config < project config < CLI flags.

Project config: .vexesrc.json

Place in your project root. vexes walks up directories (up to 20 levels) to find it.

{
  "ecosystems": ["npm", "pypi", "cargo"],
  "severity": "moderate",
  "ignore": [],
  "analyze": {
    "signals": {
      "NO_REPOSITORY": "off"
    }
  },
  "cache": {
    "dir": "~/.cache/vexes",
    "advisoryTtlMs": 3600000,
    "metadataTtlMs": 86400000
  },
  "output": {
    "color": "auto",
    "format": "text"
  }
}

User config: ~/.config/vexes/config.json

Same format as project config. Applied before project config, so project settings take priority.

Configuration options

ecosystems

Array of ecosystems to scan. Default: ["npm", "pypi", "cargo"].

Valid values: npm, pypi, cargo, brew.

CLI override: --ecosystem npm (sets a single ecosystem)

severity

Minimum severity level to report. Default: moderate.

Valid values: critical, high, moderate, low.

CLI override: --severity critical

analyze.signals

Override signal behavior. Set to "off" to disable a signal entirely.

{
  "analyze": {
    "signals": {
      "NO_REPOSITORY": "off",
      "POSTINSTALL_SCRIPT": "off",
      "RAPID_PUBLISH": "off"
    }
  }
}

cache

Option	Default	Description
dir	~/.cache/vexes	Cache directory (supports ~ expansion)
advisoryTtlMs	3600000 (1 hour)	How long advisory results are cached
metadataTtlMs	86400000 (24 hours)	How long registry metadata is cached

The cache uses SQLite (Node.js built-in node:sqlite). If the cache becomes corrupted, vexes automatically degrades to a no-op cache and continues scanning.

output

Option	Default	Description
color	auto	auto (detect TTY), always, never
format	text	text or json

CLI flag reference

Flag	Config equivalent	Description
--path <dir>	targetPath	Target directory to scan
--ecosystem <name>	ecosystems	Filter to one ecosystem
--severity <level>	severity	Minimum severity
--json	output.format: "json"	JSON output
--no-color	output.color: "never"	Disable colors
--cached	useCache: true	Use cached results without TTL check
--verbose	verbose: true	Debug output
--strict	strict: true	Fail on any signal
--deep	deep: true	Download and inspect tarballs
--fix	fix: true	Show fix commands in scan
--explain <pkg>	explain: "pkg"	Explain analysis for one package

Environment variables

Variable	Description
NO_COLOR	Disable ANSI colors (respects no-color.org convention)

Input validation

vexes validates CLI inputs:

• Ecosystem names are checked against the known list. Typos like nmp produce a warning with a "did you mean?" suggestion.
• Severity levels are validated. Invalid values fall back to moderate with a warning.
• Paths are verified to exist and be directories before scanning.