Command overview

Usage: ovecc [OPTIONS] <COMMAND>

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

These need no index: init, index, capabilities, mcp, architecture show, architecture templates, and architecture init --template — the contract is a file, so the questions answered from it alone work on day zero.

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
grep	Search from the index: definitions first, then text matches
read	One element's source: a symbol, a file:line anchor, a range, an outline

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
components	Subsystems recovered from the graph, beside the directory modules
coupling	File pairs the history keeps changing together
selfcheck	Each rule graded against the repo's own fix history

Architecture contract

Your intended architecture as code, in .ovecc/architecture.toml, checked against the real graph on every run. Start with the contract.

Command	Answers
architecture init	Draft the contract from the graph, or from a built-in template
architecture templates	The reference architectures shipped in the binary
architecture suggest	Which built-in architecture this repo already follows
architecture show	What may this file import? (no index required)
architecture diff	The contract against the real graph, with file:line
architecture check	The same, as a CI gate, with a baseline for adoption

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.