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. Requires the analysis targets to resolve inside the current directory (see "Type-aware TypeScript lane" below); otherwise the command exits with code 2.
-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

Type-aware TypeScript lane

--type-aware builds one tsconfig-driven, fully type-checked project for the whole run (the tsconfig.json at the analyzed project's root; solution-style roots follow their references) and reports what syntax-only analysis cannot prove: any that flows silently into unannotated values, non-null assertions the checker already proves unnecessary, cross-file inheritance depth, union arms that share a discriminant, defeated generic constraints, pointless type predicates, redundant utility types, and the design-principle checks (constructor dependencies on nominal concrete classes, collaborators constructed inside methods, fat interfaces with narrow clients). Findings are merged into the per-file results and summarized in a Type-aware TypeScript analysis section of the cli format; vipr explain ts-type-aware and vipr explain ts-design-principles describe each check.

The lane is project-scoped: it runs from the analyzed project's tsconfig.json, never per file, and skips (with the reason) when there is no tsconfig, when the tsconfig resolves no sources, or when the project exceeds 3,000 files. Like the tsconfig-posture and boundary sections, it anchors to a projectRoot inferred from the files and directories you pass to analyze: if everything you pass resolves inside the current directory, that stays the anchor (unchanged behavior); if every resolved target lies outside the current directory, the anchor moves to the nearest enclosing project (the closest directory above the inputs containing a tsconfig.json, package.json, or .git) — so vipr analyze ~/other-project --type-aware checks ~/other-project, not the directory you ran vipr from. When the inputs mix files inside and outside the current directory, the anchor stays at the current directory and the CLI prints a warning on stderr naming what was left out. Configuration (vipr.config.json, --env) always loads from the current directory regardless of where the anchor lands — see --config below.

Config and cache controls

Flag	Default	Description
--config <path>	(auto-detect)	Path to a vipr.config.json file. Configuration always loads from the current directory, even when the analyzed project's root differs (see "Type-aware TypeScript lane" above) — use this flag to point at a config file elsewhere.
--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

Type-check the whole project once and merge checker-backed findings into the report:

vipr analyze "src/**/*.ts" --type-aware

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