vdiff CLI Reference

Complete reference for all vdiff commands, flags, and options including analyze, graph, rules, and CI integration

Analyze (default command)

The analyze command is the default. Running vdiff with no subcommand triggers it.

Diff selection

bash

# Smart default: staged if any, else unstaged
vdiff

# Staged changes only
vdiff --staged

# All changes (staged + unstaged)
vdiff --all

# Specific commit
vdiff --commit HEAD~1

# Branch diff (PR-style review)
vdiff --base main

# Piped diff
git diff | vdiff --stdin

When no explicit flag is given, vdiff checks for staged changes first. If staged changes exist, it analyzes those (you're about to commit). If not, it falls back to unstaged changes. When smart detection picks staged and unstaged changes also exist, the footer shows a hint with the count of unstaged files not included.

Context and depth

bash

# Include full source of changed files
vdiff -f

# Deep analysis (better model + auto-includes full files)
vdiff --thinking-level high

# Verify changes against a spec, PRD, or task file
vdiff -s docs/spec.md

# Combine: deep analysis + spec verification
vdiff --thinking-level high -s docs/prd.md

# Only analyze files matching a pattern
vdiff -p "src/auth/**"

--thinking-level high automatically enables -f (full file context) and uses the more capable model configured in llm.highModel.

Output control

bash

# Verbose: show all sections and all findings
vdiff -v

# JSON output (for tooling / CI integration)
vdiff --format json

# Markdown output (for PR comments)
vdiff --format markdown

# Debug: show analysis progress and diagnostics
vdiff -d

All analyze flags

Flag	Short	Default	Description
`--staged`		`false`	Analyze staged changes only
`--all`		`false`	Analyze staged + unstaged changes
`--commit <ref>`			Analyze a specific commit
`--base <branch>`			Compare current branch against a target branch
`--stdin`		`false`	Read diff from stdin
`--files`	`-f`	`false`	Include full source of changed files
`--spec <files...>`	`-s`		Verify changes against spec/PRD/task files
`--path <glob>`	`-p`		Only analyze files matching pattern
`--thinking-level`		`low`	Analysis depth: `low` or `high`
`--format`		`pretty`	Output format: `pretty`, `json`, or `markdown`
`--verbose`	`-v`	`false`	Show all sections and all findings
`--min`		`low`	Minimum severity to display: `high`, `medium`, `low`
`--debug`	`-d`	`false`	Show analysis progress and diagnostics
`--graph <path>`	`-g`		Use a specific graph.json
`--no-graph`		`false`	Skip knowledge graph context
`--fresh`		`false`	Ignore finding registry, start clean
`--strict`		`false`	Exit non-zero on `caution` verdict
`--verify`		`false`	Extra LLM pass to cross-check HIGH severity findings
`--no-feedback`		`false`	Skip the post-run usefulness prompt

Config

Manage configuration values. Local config (.vdiff/config.json) overrides global (~/.vdiff/config.json).

bash

vdiff config set -g llm.apiKey sk-ant-...   # Set globally
vdiff config set llm.model gpt-4o-mini      # Set locally (project)
vdiff config get llm.provider               # Get a value
vdiff config list -g                        # List global config
vdiff config list                           # List merged config
vdiff config path                           # Show config file locations

All set, get, and list subcommands accept -g / --global to target the global config file.

Graph

Manage the knowledge graph (powered by Graphify). Requires Python 3.10+ and pip install graphifyy.

bash

vdiff graph init [path]    # Build a knowledge graph (default: current directory)
vdiff graph update [path]  # Incremental update
vdiff graph status         # Check graph status

The graph provides cross-file dependency context: blast radius, god nodes, community membership, and community-crossing signals. Stored at graphify-out/graph.json by default.

Rules

Define project-specific rules that persist across analyses.

bash

vdiff rule add "API routes must validate request body"
vdiff rule add --scope "src/billing/**" "Never import from orders directly"
vdiff rule list
vdiff rule remove <n>
vdiff rule clear

The --scope (-s) flag limits a rule to only apply when matching files appear in the diff. Rules are stored in .vdiff/rules/learned.md.

You can also create rule files directly in .vdiff/rules/ as .md or .txt files.

Hook

Install a pre-commit hook that runs vdiff automatically before each commit.

bash

# Install (blocks on high severity by default)
vdiff hook install

# Block on high + medium severity
vdiff hook install --block-on high,medium

# Informational only (no blocking)
vdiff hook install --block-on none

# Check if installed
vdiff hook status

# Remove the hook
vdiff hook remove

By default, the hook blocks commits that introduce high-severity findings (security, data loss, auth bypass, financial risk). Bypass with git commit --no-verify.

Configure the blocking threshold via config:

bash

vdiff config set hook.blockOn '["high","medium"]'

The hook uses a marker to identify itself and will not overwrite existing non-vdiff hooks.

IDE Integration

Install vdiff into your AI coding assistant.

bash

vdiff ide install cursor       # Cursor
vdiff ide install windsurf     # Windsurf
vdiff ide install claude-code  # Claude Code
vdiff ide install              # All detected IDEs
vdiff ide status               # Check status
vdiff ide remove cursor        # Remove

The installed rule teaches the AI assistant which vdiff commands to run, how to parse output, and how to present findings.

Review History

bash

vdiff reviews              # Browse past reviews (interactive selector)
vdiff reviews list         # List all stored reviews (non-interactive)
vdiff reviews show <index> # Show a specific past review (0 = latest)

Supports --format (pretty or json), --verbose, and --min <severity> flags.

Dismiss

Mark findings as intentionally accepted.

bash

vdiff dismiss <id>              # Dismiss a single finding
vdiff dismiss --all             # Dismiss all open findings
vdiff dismiss <id> --reason "Intentional design decision"

Without an id or --all, prints the list of open findings.

Metrics

View structural health metrics from your knowledge graph.

bash

vdiff metrics                    # Show metrics (requires graph.json)
vdiff metrics --format json      # JSON output for tooling

Displays complexity, coupling, and health metrics derived from your dependency graph.

Exit Codes

Code	Meaning
`0`	Verdict is `ready` or `caution`
`1`	Verdict is `not_ready`

With --strict, caution also exits 1.

← Getting Started with vdiff vdiff Configuration Guide→