Vipr CLI

Vipr CLI analyzes TypeScript, JavaScript, React, and Next.js codebases for complexity, maintainability, security, accessibility, performance, and framework-specific issues.

Use it locally while coding, in CI to enforce quality gates, or in scripts that need structured JSON or Markdown reports.

Install

Vipr CLI requires Node.js >=22.22.0.

npm install -g @vipr/cli

Run it without a global install:

npx --yes @vipr/cli analyze 'src/**/*.{ts,tsx}'

Quick Start

# Analyze a single file
vipr analyze src/App.tsx

# Analyze a directory or glob
vipr analyze 'src/**/*.{ts,tsx}'

# Write structured JSON output
vipr analyze 'src/**/*.{ts,tsx}' -f json -o vipr-report.json

# Fail CI on low scores or critical findings
vipr analyze 'src/**/*.{ts,tsx}' -t 70 --fail-on-critical

# Generate a starter configuration file
vipr init

analyze is the default command, so vipr 'src/**/*.{ts,tsx}' is equivalent to vipr analyze 'src/**/*.{ts,tsx}'.

Output Formats

| Format | Description | | ----------- | --------------------------------------------------------------- | | cli | Human-readable terminal output with grouped findings and scores | | json | Structured JSON for CI pipelines, scripts, and other tooling | | json-full | Full JSON output with all available analysis detail | | markdown | Markdown report for pull requests, issues, or documentation |

Use --compact with json or json-full to minify the output.

Common Options

| Flag | Description | | ------------------------------ | -------------------------------------------------------------------------- | | -f, --format <type> | Output format: cli, json, json-full, markdown | | -o, --output <file> | Write output to a file instead of stdout | | -p, --plugins <list> | Run only selected plugins such as react or core | | -c, --categories <list> | Limit output to categories such as security,performance | | -r, --report <types> | Show specific report selectors such as overview or typescript:overview | | -s, --min-severity <level> | Minimum severity to report: info, warning, critical | | -t, --fail-threshold <score> | Exit with code 1 if any file scores below the threshold | | --fail-on-critical | Exit with code 1 if any critical finding is reported | | --changed [ref] | Analyze only files changed since a git ref such as HEAD or main | | --config <path> | Use a specific vipr.config.json file | | --no-config | Skip config file loading entirely | | --timing | Show execution timing | | -q, --quiet | Suppress non-essential output | | -d, --debug | Enable debug logging |

Run vipr analyze --help for the complete option list.

Configuration

Vipr looks for vipr.config.json by walking up from the current working directory. CLI flags override config file values.

{
  "$schema": "https://vipr.dev/schemas/vipr-config.schema.json",
  "output": {
    "format": "cli",
    "failThreshold": 70,
    "failOnCritical": true
  }
}

Generate a starter config interactively:

vipr init

CI Example

- name: Run Vipr analysis
  run: |
    npx --yes @vipr/cli analyze 'src/**/*.{ts,tsx}' \
      -f json \
      -o vipr-report.json \
      -q \
      --fail-threshold 70 \
      --fail-on-critical

- name: Upload report
  uses: actions/upload-artifact@v4
  with:
    name: vipr-report
    path: vipr-report.json

Exit Codes

| Code | Meaning | | ---- | ----------------------------------------------------------------------------- | | 0 | Analysis completed and all configured thresholds passed | | 1 | Analysis failed, thresholds were triggered, or the command could not complete |

Troubleshooting

Quote glob patterns so your shell does not expand them before Vipr sees them:

# Correct
vipr analyze 'src/**/*.tsx'

# Incorrect
vipr analyze src/**/*.tsx

Use vipr -i to launch interactive mode when you want prompts instead of passing file arguments.

If you need more detail while debugging a run:

vipr analyze 'src/**/*.{ts,tsx}' --debug --timing

If you suspect stale results from caching:

vipr analyze 'src/**/*.{ts,tsx}' --no-cache --no-persistent-cache

Documentation

• Vipr CLI docs
• vipr --help
• vipr analyze --help

License

MIT