CLI reference
Every command vidi accepts, generated from the binary itself.
Commands that only read are safe to run at any time. Commands that write
require vidi init and a login.
Commands at a glance
| Command | What it does |
|---|---|
scan | Walk the repo into addressable units, content-hash each, and harvest references, one deterministic tree descent |
report | Coverage report: what is covered, the obligations, and the re-review queue ordered by significance x severity |
status | One-line gate status; add –porcelain for a stable scriptable form |
queue | The re-review queue: gating obligations first, then significance x churn severity |
verify | The gate: resolve every obligation against the ledger, emit the three-state check-run and the exit code |
explain | Explain WHY the gate reads the way it does: render every failure (stale, orphan, unreviewed, migration-needed, requirement shortfalls, and rejected ledger lines) into plain-English category -> what-failed -> why -> what-to-do diagnostics |
verify-vouches | Verify the SIGNATURES on the committed vouches against the notary key: every signed DSSE envelope in .vidi/reviews.jsonl must verify under the notary’s Ed25519 key (cached at .vidi/notary.pub, so this is offline once the key is known); an unsigned vouch verifies as self-asserted (the free baseline, never a failure) |
push | Push the coverage artifact to the hosted portal (POST /api/v1/ingest), the paid lane: a resolvable remote (URL + bearer) is required |
pull | Pull the tenant’s reviews and revocations from the hosted portal and union-merge them into the local ledgers (GET /api/v1/reviews) |
churn | Advisory churn for one unit: state and severity band (never gates) |
significance | Advisory significance ranking: orders within each re-review queue stratum; never gates |
graph | Bounded call-graph neighborhood around a unit as JSON: {from, callees, callers} (advisory; depth <= 2) |
show | Show the exact bare statement(s) for a content_id or unit address; add –json for the machine shape |
json | Machine report of every unit; add –significance for the within-repo percentile |
init | Initialize vidi in this repo: create the in-repo .vidi/ files |
review | Review one unit interactively (rigor + verdict), appending to the in-repo ledger |
vouch | One-shot approved review of a unit, or a whole commit with –commit |
revoke | Revoke a review by content_id or unit address (revoke-wins; never needs the notary) |
sign | Sign a review through the notary, a logged-in human; refused for automated agents |
whoami | Resolve who you are: person-bound, before any tenant |
attribute | Record model authorship (advisory; never gates): import git-ai’s refs/notes/ai attestation for HEAD into .vidi/authorship.jsonl, AI lane only, fail-toward-unknown |
hooks | Manage the post-commit hook that runs vidi attribute after each commit, the routine authorship-capture cadence |
history | Forensics over git history: when could AI coding tools first have touched this repo? vidi history audit sweeps every ref for AI-tool commit signatures and config-file first-adds and derives the worst-case AI-era start date |
login | Log in so writes are authorized, machine-wide, like git config --global |
logout | Log out on this machine: best-effort revoke the hosted refresh token, then always clear the locally stored hosted and offline credentials |
vidi scan
vidi scan [OPTIONS]
Walk the repo into addressable units, content-hash each, and harvest references, one deterministic tree descent. Read-only; never writes .vidi/
Usage: vidi scan [OPTIONS]
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi report
vidi report [OPTIONS]
Coverage report: what is covered, the obligations, and the re-review queue ordered by significance x severity
Usage: vidi report [OPTIONS]
Options:
--sarif
Emit SARIF 2.1.0 (files-changed annotations for CI) instead of the human report
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi status
vidi status [OPTIONS]
One-line gate status; add --porcelain for a stable scriptable form
Usage: vidi status [OPTIONS]
Options:
--porcelain
Stable, line-oriented output for scripts
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi queue
vidi queue [OPTIONS]
The re-review queue: gating obligations first, then significance x churn severity
Usage: vidi queue [OPTIONS]
Options:
--top <N>
Show only the top N entries (default: 20)
--all
Show every entry instead of the top 20
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi verify
vidi verify [OPTIONS]
The gate: resolve every obligation against the ledger, emit the three-state check-run and the exit code. Fails closed on any ambiguity
Usage: vidi verify [OPTIONS]
Options:
--json
Emit the machine gate object (vidi.gate/v1) instead of the human gate output. The full report is `vidi json` (vidi.json/v1.0); the gate object has its own schema id so consumers never validate it against vidi-json-v1.schema.json
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi explain
vidi explain [OPTIONS] [PATH]
Explain WHY the gate reads the way it does: render every failure (stale, orphan, unreviewed, migration-needed, requirement shortfalls, and rejected ledger lines) into plain-English category -> what-failed -> why -> what-to-do diagnostics. Read-only; runs the same reader/gate path as `verify` and never writes .vidi/. Add --json for the structured form; pass a path to scope the explanation to one file or unit
Usage: vidi explain [OPTIONS] [PATH]
Arguments:
[PATH]
Scope the explanation to one file or unit address (prefix match on a segment boundary, e.g. `src/auth.rs` or `src/auth.rs::fn:verify`). Rejected ledger lines are repo-wide and always shown
Options:
--json
Emit the machine object (vidi.explain/v1) instead of the human diagnostics
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi verify-vouches
vidi verify-vouches [OPTIONS]
Verify the SIGNATURES on the committed vouches against the notary key: every signed DSSE envelope in `.vidi/reviews.jsonl` must verify under the notary's Ed25519 key (cached at `.vidi/notary.pub`, so this is offline once the key is known); an unsigned vouch verifies as self-asserted (the free baseline, never a failure). Exits non-zero if any signed line fails to verify or any line is undecodable (fail-closed). Distinct from `verify`, the orphan/stale/scope coverage gate
Usage: vidi verify-vouches [OPTIONS]
Options:
--url <URL>
The notary base URL (else `$VIDI_REMOTE_URL`). Optional: with a cached `.vidi/notary.pub`, verification is fully offline and needs neither this nor a token
--token <TOKEN>
The notary bearer token (else `$VIDI_REMOTE_TOKEN`). Only consulted for an online key fetch when no key is cached; unused on the offline path
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi push
vidi push [OPTIONS]
Push the coverage artifact to the hosted portal (`POST /api/v1/ingest`), the paid lane: a resolvable remote (URL + bearer) is required. Read/transport verb; stays open to agents (CI is its home; see the push-gate note in push.rs)
Usage: vidi push [OPTIONS]
Options:
--repo <REPO>
Host-qualified repo slug, e.g. `github.com/vidivouch/vid`. Defaults to `$GITHUB_REPOSITORY`, else the repo's `origin` remote
--commit <COMMIT>
The commit the snapshot is for (default: `$GITHUB_SHA`, else `git rev-parse HEAD`)
--branch <BRANCH>
The branch the snapshot is for (the portal's grouping dimension). Defaults to `$GITHUB_REF_NAME` / `$CI_COMMIT_REF_NAME`, else the current HEAD branch, else its upstream; a detached checkout lands the snapshot unbranched
--file <FILE>
Push a pre-generated `vidi.json` instead of recomputing (`-` reads stdin)
--url <URL>
The remote base URL (else `$VIDI_REMOTE_URL`, else the production host)
--token <TOKEN>
The bearer token (else `$VIDI_REMOTE_TOKEN`, else the stored `vidi login` token)
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi pull
vidi pull [OPTIONS]
Pull the tenant's reviews and revocations from the hosted portal and union-merge them into the local ledgers (`GET /api/v1/reviews`). The paid hydrate lane: a resolvable remote is required. Read/hydrate verb; open to agents
Usage: vidi pull [OPTIONS]
Options:
--repo <REPO>
Host-qualified repo slug, e.g. `github.com/vidivouch/vid`. Defaults to `$GITHUB_REPOSITORY`, else the repo's `origin` remote (same ladder as `push`). Person logins send it to select the repo; tenant API tokens remain tenant-scoped
--url <URL>
The remote base URL (else `$VIDI_REMOTE_URL`, else the production host)
--token <TOKEN>
The bearer token (else `$VIDI_REMOTE_TOKEN`, else the stored `vidi login` token)
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi churn
vidi churn [OPTIONS] <UNIT>
Advisory churn for one unit: state and severity band (never gates)
Usage: vidi churn [OPTIONS] <UNIT>
Arguments:
<UNIT>
The unit address to describe
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi significance
vidi significance [OPTIONS]
Advisory significance ranking: orders within each re-review queue stratum; never gates
Usage: vidi significance [OPTIONS]
Options:
--top <N>
Show only the top N units
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi graph
vidi graph [OPTIONS] --from <UNIT>
Bounded call-graph neighborhood around a unit as JSON: {from, callees, callers} (advisory; depth <= 2). The editor plugins parse this shape
Usage: vidi graph [OPTIONS] --from <UNIT>
Options:
--from <UNIT>
The unit address to center the neighborhood on
--depth <N>
Neighborhood depth (bounded at 2)
[default: 2]
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi show
vidi show [OPTIONS] <CONTENT_ID|UNIT>
Show the exact bare statement(s) for a content_id or unit address; add --json for the machine shape
Usage: vidi show [OPTIONS] <CONTENT_ID|UNIT>
Arguments:
<CONTENT_ID|UNIT>
The statement(s) to show: a content_id (32 lowercase hex, printed when a vouch or review is recorded), or a unit address (`<file>::<qualpath>` from `vidi json`) showing every ledger statement for that unit
Options:
--json
Emit the exact bare-statement JSON (matches contracts/D2-provenance-core.json; one document per line when several statements match)
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi json
vidi json [OPTIONS]
Machine report of every unit; add --significance for the within-repo percentile
Usage: vidi json [OPTIONS]
Options:
--significance
Add one optional int per unit: the within-repo significance percentile (0-100)
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi init
vidi init [OPTIONS]
Initialize vidi in this repo: create the in-repo .vidi/ files. The visible opt-in act: vidi's state-writing verbs refuse a repo that has not run it
Usage: vidi init [OPTIONS]
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi review
vidi review [OPTIONS] <UNIT>
Review one unit interactively (rigor + verdict), appending to the in-repo ledger
Usage: vidi review [OPTIONS] <UNIT>
Arguments:
<UNIT>
The unit address, e.g. src/auth.rs::fn:verify_token
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi vouch
vidi vouch [OPTIONS] [UNIT]
One-shot approved review of a unit, or a whole commit with --commit
Usage: vidi vouch [OPTIONS] [UNIT]
Arguments:
[UNIT]
The unit address to vouch (omit when using --commit)
Options:
--rigor <RIGOR>
Review rigor: skimmed | read-fully | ran-tests
--commit <REF>
Vouch a whole commit by git ref instead of a unit
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi revoke
vidi revoke [OPTIONS] <CONTENT_ID|UNIT>
Revoke a review by content_id or unit address (revoke-wins; never needs the notary)
Usage: vidi revoke [OPTIONS] <CONTENT_ID|UNIT>
Arguments:
<CONTENT_ID|UNIT>
The review to revoke: a content_id (32 lowercase hex), or a unit address (`<file>::<qualpath>`) resolving to exactly one active review
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi sign
vidi sign [OPTIONS] <UNIT>
Sign a review through the notary, a logged-in human; refused for automated agents
Usage: vidi sign [OPTIONS] <UNIT>
Arguments:
<UNIT>
The unit address to sign
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi whoami
vidi whoami [OPTIONS]
Resolve who you are: person-bound, before any tenant
Usage: vidi whoami [OPTIONS]
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi attribute
vidi attribute [OPTIONS]
Record model authorship (advisory; never gates): import git-ai's refs/notes/ai attestation for HEAD into .vidi/authorship.jsonl, AI lane only, fail-toward-unknown
Usage: vidi attribute [OPTIONS]
Options:
--hook <HARNESS>
The agent harness that fired this invocation as a hook (e.g. post-tool-use). Optional context only: bare `vidi attribute` runs the same import
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi hooks
vidi hooks [OPTIONS] <COMMAND>
Manage the post-commit hook that runs `vidi attribute` after each commit, the routine authorship-capture cadence. The hook is advisory and fail-open: it runs in the background and can never block or fail a commit
Usage: vidi hooks [OPTIONS] <COMMAND>
Commands:
install Install the post-commit authorship hook. An existing post-commit hook is appended to, never replaced; installing twice is a no-op
status Show whether the hook is installed, whether other post-commit content coexists, and whether the hook is currently disabled
uninstall Remove vidi's hook block. Any other post-commit content is preserved byte-exact
help Print this message or the help of the given subcommand(s)
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi history
vidi history [OPTIONS] <COMMAND>
Forensics over git history: when could AI coding tools first have touched this repo? `vidi history audit` sweeps every ref for AI-tool commit signatures and config-file first-adds and derives the worst-case AI-era start date. Read-only, works before `vidi init` on any git repo; advisory only (never gates)
Usage: vidi history [OPTIONS] <COMMAND>
Commands:
audit Sweep every ref for AI-tool commit signatures and config-file first-adds, derive the worst-case AI-era start date, and report. Signature dates are earliest-evidence lower bounds; absence of signature proves nothing. Read-only: report + cache, nothing recorded
help Print this message or the help of the given subcommand(s)
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi login
vidi login [OPTIONS] [IDENTITY]
Log in so writes are authorized, machine-wide, like `git config --global`. Two ways: `vidi login` connects your vidivouch.com account (device flow; stores only a revocable bearer token, no signing key); `vidi login --local` records an offline self-asserted identity: enough for the free tier
Usage: vidi login [OPTIONS] [IDENTITY]
Arguments:
[IDENTITY]
The self-asserted identity to record with --local (e.g. your email or a handle). Defaults to `git config user.email` when omitted. Only valid with --local
Options:
--local
Establish a LOCAL self-asserted identity (offline; no hosted account, no network) instead of the device flow. The free-tier write login: writes require being logged in, and this is the login that needs no server. Identity assurance stays self-asserted; the paid lane is the notary presence ceremony, never this
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')
vidi logout
vidi logout [OPTIONS]
Log out on this machine: best-effort revoke the hosted refresh token, then always clear the locally stored hosted and offline credentials
Usage: vidi logout [OPTIONS]
Options:
--color <COLOR>
When to colourise output: `auto` (a terminal, honouring NO_COLOR), `always`, or `never` (byte-identical to the plain human-output contract). Machine surfaces (--json / --porcelain / SARIF) are never coloured regardless
Possible values:
- auto: Colourise when stdout is a terminal
- always: Always colourise
- never: Never colourise (the scriptable form)
[default: auto]
-h, --help
Print help (see a summary with '-h')