Command overview

Usage: ovecc [OPTIONS] <COMMAND>

Every command reads the model that ovecc index persisted into .ovecc/ (except init, index, capabilities, and mcp themselves), renders in multiple formats, and returns stable exit codes. All commands are also exposed 1:1 as MCP tools.

All commands

Foundation

Command	Answers
init	Set up a repository: commented config, .gitignore entry
index	Build or update the local architecture database
capabilities	The machine-readable contract: commands, metrics, rules, exit codes
summary	One-screen architecture health
report	One-shot report: summary + cycles + violations + security + hotspots

Findings

Command	Answers
violations	Every architecture + security finding, with file:line
security	Secrets, insecure patterns, weak crypto, tainted flows
audit	Known-vulnerable dependencies (offline OSV)
health	Functions over the complexity thresholds
deadcode	Unused exports, unreachable files, phantom/unused dependencies
dupes	Duplicated code (clone families)
fix	Apply the mechanical fixes (dry-run by default)

Architecture intelligence

Command	Answers
diagnose	Named architectural smells + evidence + remediation
advise	Everything touching one file/module, with fixes — call before editing
metrics	Per-component Martin metrics (fan-in/out, instability, distance)
explain	Deterministic explanation of an element's role
impact	Blast radius of changing a module / symbol / API / table
query	Structured graph queries: deps, rdeps, paths, cycles, reachability
export	Context slice as JSON, or the dependency graph (JSON / HTML viewer)
hotspots	Technical-debt ranking: churn × coupling × ownership × violations
conventions	Conventions learned from the repo, and deviations

Change scope (PR loop)

Command	Answers
review	The NAMED new defects a change introduced
gate	Pass/fail CI verdict on new cycles / violations / regressions
diff	Raw structural deltas between two snapshots
drift	Metric trend between snapshots: better or worse?
history	One metric across every snapshot, with a sparkline

Integration

Command	Answers
mcp	MCP server over stdio: every command as an agent tool

Global options

Every command accepts:

Option	Effect
--repo <PATH>	Operate on this repository (default: the current directory)
--format <FORMAT>	text (default), json, ndjson, markdown — plus sarif and codeclimate for finding-shaped output. Default is configurable via [output] default_format
--stats	Print wall-clock and peak-memory stats to stderr (for index: per-phase breakdown)
--no-meta	Omit the self-describing meta block from JSON output (the MCP server sets this automatically)

Exit codes

Code	Name	Meaning
0	success	Command succeeded; no gating threshold crossed
1	findings_present	A --fail-on threshold was crossed (findings/cycles/risk)
2	usage	CLI usage error (bad arguments)
3	repository	Repository or configuration error
4	index	Index or database error (e.g. database missing)
5	parser	Parser error
6	git	Git error
7	internal	Unexpected internal error

A downstream reader closing the pipe early (ovecc report | head, quitting a pager) is not an error: output stops quietly and the exit code is 0. More in the exit-code reference.

Determinism

Every command is deterministic: an unchanged database renders byte-identical output. Paths are repo-relative with POSIX separators in every format.