CLI Commands

This reference documents the public, customer-facing CLI surface. It covers the commands most users need day to day: analyze and init.

Usage

vipr [command] [files...] [options]

analyze is the default command. Running vipr <files> is equivalent to vipr analyze <files>.

vipr analyze

Analyze files for complexity, anti-patterns, architecture signals, security issues, accessibility problems, and more.

vipr analyze [files...] [options]

Arguments

Argument	Description
files...	One or more file paths or glob patterns to analyze

Input and selection

Flag	Default	Description
--changed [ref]	HEAD	Analyze only files changed since the given git ref
-c, --categories <list>	(all)	Comma-separated list of categories to include, such as security,performance
-p, --plugins <list>	(all)	Comma-separated list of plugin IDs to run, such as react,core
-r, --report <types>	(all)	Comma-separated report selectors. Bare selectors like overview match every plugin report with that reportType; qualified selectors like typescript:overview match one exact plugin report.
-i, --interactive	false	Launch the interactive prompt flow

Output and presentation

Flag	Default	Description
-f, --format <type>	cli	Output format: cli, json, json-full, or markdown
-o, --output <file>	(stdout)	Write output to a file instead of stdout
--compact	false	Minify JSON output. Only valid with json or json-full
-s, --min-severity <level>	info	Minimum severity to report: info, warning, or critical
-q, --quiet	false	Suppress non-essential output

Execution and diagnostics

Flag	Default	Description
-d, --debug	false	Enable debug logging to stderr
--verbose	false	Enable verbose output; same effect as debug logging in the CLI
--timing	false	Show execution timing after analysis completes

Config and cache controls

Flag	Default	Description
--config <path>	(auto-detect)	Path to a vipr.config.json file
--env <name>	(none)	Apply env.<name> overrides from config
--no-config	false	Skip configuration file loading entirely
--no-cache	false	Disable in-memory result caching
--no-parallel	false	Disable worker-thread parallelism
--no-persistent-cache	false	Disable the persistent disk cache

Quality gates

Flag	Default	Description
-t, --fail-threshold <score>	0	Exit with code 1 if any file score falls below this value (0-100)
--fail-on-critical	false	Exit with code 1 if any critical-severity insight is found

Examples

Analyze a single file:

vipr analyze src/components/Dashboard.tsx

Analyze a directory:

vipr analyze "src/**/*.{ts,tsx}"

Inputs expand first, then include, exclude, and global.ignorePatterns from vipr.config.json filter the target set.

Limit output to React findings:

vipr analyze "src/**/*.{tsx,jsx}" --plugins react

Show only overview reports:

vipr analyze "src/**/*.{ts,tsx}" --report overview

Analyze only files changed since main:

vipr analyze "src/**/*.{ts,tsx}" --changed main

Fail CI on low scores or critical findings:

vipr analyze "src/**/*.{ts,tsx}" --fail-threshold 70 --fail-on-critical

Write a Markdown report without console noise:

vipr analyze "src/**/*.{ts,tsx}" --format markdown --output vipr-report.md --quiet

Interactive mode

When no files are specified and a TTY is available, Vipr automatically launches interactive mode. You can also force it:

vipr -i

vipr init

Create a canonical vipr.config.json file at the detected Git repository root. If no Git root is found, Vipr writes to the current working directory. In a TTY, Vipr opens an interactive wizard by default.

vipr init [options]

Flag	Default	Description
-f, --force	false	Overwrite an existing configuration file
-p, --preset <type>	default	Configuration preset: default, strict, or lenient
-q, --quiet	false	Skip the interactive wizard and use preset defaults

Presets

Preset	Behavior
default	Balanced defaults for most teams
strict	Higher score expectations and stricter thresholds
lenient	Lower enforcement thresholds for gradual adoption

Examples

Create a config interactively:

vipr init

Create a strict config without prompts:

vipr init --preset strict --quiet

Overwrite an existing file:

vipr init --force --preset default --quiet

Global options

Flag	Description
-h, --help	Display help
-v, --version	Display the version