Skip to main content

CLI API Reference

This page is the compact contract for the public Vipr CLI. Use it when you want the shortest path from a task to the right flag, output mode, or config knob.

What the CLI can do

Capability Main surface
Analyze files, globs, or changed files vipr analyze [files...], --changed [ref]
Narrow the analysis scope --plugins, --categories, --report
Shape the output --format, --output, --compact, --min-severity, --quiet
Enforce CI gates --fail-threshold, --fail-on-critical
Tune execution --debug, --verbose, --timing, --no-cache, --no-parallel, --no-persistent-cache
Scaffold config vipr init, --force, --preset, --quiet

Command model

vipr is the top-level binary. analyze is the default command, so vipr <files> and vipr analyze <files> are equivalent.

Command Purpose
analyze Run analysis over file paths or glob patterns
init Create a starter vipr.config.json file

Analyze surface

analyze accepts one or more file paths or glob patterns. It can also narrow the input set to files changed since a git ref.

Key selectors:

  • --changed [ref] compares the provided files against a git ref, defaulting to HEAD
  • --plugins <list> runs only the named plugin IDs
  • --categories <list> limits output to the selected categories
  • --report <types> selects report presenters by bare or qualified selector

Output and execution controls:

  • --format <type> chooses cli, json, json-full, or markdown
  • --output <file> writes the formatted result to a file
  • --compact minifies json and json-full
  • --min-severity <level> filters visible insights by severity
  • --quiet suppresses non-essential console output
  • --debug and --verbose enable debug logging
  • --timing prints execution timing after the run
  • --no-cache, --no-persistent-cache, and --no-parallel control runtime behavior
  • --env <name> applies env.<name> overrides from vipr.config.json

Quality gates:

  • --fail-threshold <score> exits with code 1 when any file drops below the threshold
  • --fail-on-critical exits with code 1 when any critical insight is reported

Init surface

init creates a starter vipr.config.json at the detected Git repository root, falling back to the current working directory when no Git root exists.

Flag Default Purpose
-f, --force false Overwrite an existing config file
-p, --preset <type> default Choose default, strict, or lenient starter values
-q, --quiet false Skip the interactive wizard and write defaults directly

Configuration model

Vipr loads vipr.config.json by walking up from the current working directory unless you override the path with --config or skip config loading with --no-config.

The shared config loader merges settings in this order:

  1. System defaults
  2. Extended config files from extends
  3. Project config
  4. Environment overrides from env when --env <name> is supplied
  5. Explicit CLI overrides

Commander defaults do not overwrite config values. Only flags explicitly passed by the user become CLI overrides.

Exit codes

Code Meaning
0 Analysis completed and all configured thresholds passed
1 Analysis failed, a gate tripped, or the command could not complete
Documentation