CLI Overview

The AVC CLI is the primary interface — every other surface (VSCode extension, web UI, MCP server) calls these commands underneath. Each command supports --json for machine-readable output.

Global flags

Flag	Description
--json	Emit results as JSON to stdout instead of human-readable text
--help	Show help for any command

Errors are written to stderr; the process exits with code 1 on failure.

Project setup

avc init Initialize AVC for a project. Optionally set up agent integration files.

Snapshots

avc snapshot Create a snapshot of the current project state.

avc list List snapshots on the active branch.

avc info Show snapshot metadata and file list.

avc log Tree-style history of snapshots.

avc delete Permanently delete a snapshot.

Diff & restore

avc diff Compare two snapshots file-by-file.

avc diff-current Compare a snapshot against the working tree.

avc restore Roll back the entire project to a snapshot.

avc restore-file Restore a single file from a snapshot.

avc undo Reverse the last restore or merge, zero arguments.

avc cat Print file contents from a snapshot to stdout.

avc file-history List every snapshot that contains a specific file.

avc annotate Show which snapshot introduced each line.

Continuous safety & history

avc watch Continuously checkpoint the project as files change.

avc timeline Branch history grouped by agent session.

avc bisect Find the snapshot that broke a command, O(log n).

Branches & merge

avc branch Create, stack, list, switch, delete, and diff branches.

avc merge Line-level three-way merge, protected paths, and merge trains.

Agents & UI

avc mcp Start the MCP server for AI agents.

avc ui Start the standalone web UI server.

avc run Run a sandboxed command inside a branch workspace.

Maintenance & status

avc status Show files changed since the last snapshot.

avc verify Audit stored history for corruption.

avc trash Recover files quarantined by a restore.

avc gc Garbage-collect unreferenced objects from the object store.

avc storage Show AVC disk usage for the current project.

avc cache Manage the diff result cache.

Import & export

avc export Export AVC history to a portable archive.

avc import Import AVC history from an archive.

JSON output convention

Every command that returns structured data accepts --json. The shape mirrors what’s documented per-command. Errors always include an error field:

{ "error": "snapshot 'snap-foo' not found" }

For scripts and agents, prefer --json — it’s stable across CLI text-output revisions.