Command reference¶

The tovio commands, with synopsis, flags, examples, and exit code. Commands that do not have a section of their own are inventoried in Other commands at the end. For the conventions shared by all commands — --json, -q/--quiet, --format, color, and aliases — see Global flags. Error codes and the structured --json shape live in the Error reference.

Each command lists its interaction tier (Everyday / Team / Advanced), which controls discovery in tovio help, not capability. Phase labels identify roadmap ownership; they do not mean the command is unavailable. Capability-specific omissions are called out explicitly.

Unless noted otherwise, every command accepts the global flags, supports --json, and — where it mutates state — is recorded in the op-log and reversible with tovio undo.

Exit codes at a glance

Exit codes are coarse — one class per area — so scripts branch on category while the precise code lives in --json.code. 0 success · 2 CLI usage · 7 storage · 11 crypto/key · 13 permission/token · 17 sync · 19 change/op-log · 21 migration. Full table in the Error reference. Storing a conflict is success (exit 0).

`tovio init`¶

Everyday · Phase 0.

tovio init [--mode simple|team|agentic] [--no-ignores]

Creates a new TOVIO repository in the current directory (it takes no path argument). On an interactive TTY it asks exactly one question — the collaboration mode — and proceeds; --mode answers it up front, and a non-interactive run defaults to Simple Mode. Team and Agentic Mode bootstrap the owner's identity keypair and a self-sovereign Key Authority without any ceremony; Simple Mode creates no cryptographic identity at all (add one later with tovio identity init).

Flag	Meaning
`--mode simple`	Solo: no identity, no policies (Tier 0). The default.
`--mode team`	Bootstraps an identity and a self-sovereign Key Authority; unlocks `access`/`policy`/`identity`/`key` (Tier 1).
`--mode agentic`	Team Mode plus agent registration (`tovio agent new`) enabled.
`--no-ignores`	Do not write a `.tovioignore` for the generated paths already present in the directory.

$ tovio init --mode simple
✓ Initialized empty TOVIO repository in /path/to/project/.tovio
  On branch main · current change chg:ssq4n1td15aj2fdsj7pzhrb614 · mode: simple
  → Next: edit files, then `tovio commit -m "…"`

Exit: 0 on success. 2 (TVO-CLI-004) if a repository already exists in this directory.

`tovio quickstart`¶

Everyday · Phase 0.

tovio quickstart [--topic <topic>] [--no-cleanup]

A first-class interactive tutorial — the cargo new of TOVIO. Walks you through your first repository, change, commit, sync, conflict, and (optionally) first policy and agent. Each step teaches one concept, runs the exact command, shows tovio status after, and reminds you that tovio undo reverses it.

Flag	Meaning
`--topic <topic>`	Jump to one lesson: `basics`, `branches`, `conflicts`, `policy`, `agents`. Default: `basics`.
`--no-cleanup`	Keep the scratch repository the tutorial creates (default: removed on exit).

Exit: 0.

`tovio clone`¶

Everyday · Phase 3.

tovio clone <remote> <repo-id> <dir> [--cert <path>] [--sparse <glob>]… [--depth <n>]
            [--blobless] [--blob-limit <bytes>] [--no-attachments]

Clones a repository into a new directory from a native relay (host:port, pinned with --cert) or a hosted Forge (https://host[/base], trusted via public PKI). Policy objects arrive as ciphertext and are decrypted on access only if the local identity's attributes satisfy them — a full clone stays encrypted to anyone without clearance.

Pick one partial mode. A path scope and an object filter are two different ways to clone less, and letting one silently win would be worse than refusing, so --sparse cannot be combined with --depth, --blobless, --blob-limit or --no-attachments; --blobless and --blob-limit are likewise mutually exclusive.

Flag	Meaning
`--cert <path>`	The relay's DER certificate to trust (the file `tovio serve` writes). Required for a native `host:port` relay; omit for a hosted `https://` Forge.
`--sparse <glob>`	Clone only objects under these paths. Repeatable.
`--depth <n>`	Shallow clone: the tip plus `<n>` commits of history (extend later with `tovio fetch --deepen`).
`--blobless`	Omit all file content; it backfills lazily on read.
`--blob-limit <bytes>`	Omit file content larger than `<bytes>`; smaller files still clone.
`--no-attachments`	Defer the semantic/behavioral closure (fetched on demand by `semantic diff` and friends).

$ tovio clone forge.example.dev:7743 <repo-id> my-project --cert relay-cert.der --sparse "src/**"

Exit: 0 on success; 17 (TVO-SYNC-001) if the remote is unreachable.

`tovio status`¶

Everyday · Phase 0.

tovio status [--conflicts] [--prompt] [--json] [-q]

The single source of truth. Any time you are unsure of repository state, this command answers. It shows the lane and current change, relay ahead/behind, modified files with protection indicators, open conflicts, isolated paths, active locks, and active agent sessions with their expiry. It is complete enough that no other command is needed to interpret state.

Flag	Meaning
`--conflicts`	Also report whether the current lane lands cleanly onto `main` (read-only).
`--prompt`	Emit a compact one-line segment for a shell prompt (Starship / p10k): `<lane> <short-change> [✚changed] [✖conflicts] [⏳token-expiry]`. `--json` gives its fields.

In a Simple-Mode repository with no policies and no agents, the protection and agent sections are omitted entirely.

$ tovio status
  on feature/cgm-sync · chg:a3f7b2h8xk0m9v2qp4r7t1nc5w
  relay origin · ahead 3, behind 0
  modified (3 file(s))
    ~ src/integrations/cgm/dexcom.ts
    + tests/integrations/cgm.test.ts
    ~ config/production/feature-flags.env   🔒 protected
  1 unresolved conflict(s) on the lane — resolve: `tovio resolve <path>` (details: `tovio conflicts`)
    ⚠ content       src/shared/types.ts
  1 active agent session(s):
    ⚡ cap_7f2a91  refactor-bot  model claude-opus-4 · branches agent/refactor-bot/** · expires in ~2h

The --json form carries the same state as a structured result. It never prints the contents of a policy the caller is not authorized to read.

Exit: 0 (always, including with open conflicts).

`tovio commit`¶

Everyday · Phase 0.

tovio commit [-m <message>] [--amend] [--token <token-id> [--prompt <text>]] [--no-generate]
             [--session-from <runtime|path>] [--no-session]

Finalizes the current change into an immutable commit and starts a new change. The change's Change ID (chg:<base32>) was assigned when work began and is preserved. There is no tovio add and no staging — every tracked modification is already part of the change.

Flag	Meaning
`-m`, `--message <message>`	The commit message. Required with `--json`/`--quiet` or no TTY.
`--amend`	Fold the current working change into the last commit instead of creating a new one; with `-m` its message is rewritten, without `-m` the existing message is kept. The Change ID is preserved. Refused on a lane with no commits.
`--token <token-id>`	Commit as an agent under a capability token (its id, from `tovio agent new`). The token's path/lane scope is enforced before anything is sealed, and the commit records agent provenance.
`--prompt <text>`	With `--token`: the initiating prompt; its BLAKE3 hash is recorded in provenance.
`--no-generate`	Skip the opt-in config-as-code regeneration (`ci.generate=on`) for this commit.
`--session-from <runtime\\|path>`	Capture this commit's agent transcript from a named runtime (`claude-code`, `codex`, `open-transcript`) or a file, instead of discovering one. Capture is on by default; the result is an observed, unattested session.
`--no-session`	Do not capture an observed session for this commit.

When -m is omitted on a TTY, commit prompts for the message. With --json, --quiet, or no TTY, -m is required.

$ tovio commit -m "Add Dexcom G7 sync handler"

Exit: 0 on success. 2 (TVO-CLI-019) if -m is absent under --json/--quiet/no TTY. 19 (TVO-OP-003) if there is nothing to commit; 19 (TVO-OP-020) for --amend on a lane with no commit yet.

`tovio log`¶

Everyday · Phase 0.

tovio log [<path>] [--limit <n>] [--entity agent|human] [--task-id <id>] [--format <fmt>]
          [--date relative|absolute] [--graph | --no-graph] [--first-parent] [--all] [--oneline]
          [--why] [-S <string>] [-G <regex>] [--session <chg>] [--descendants <chg>] [--no-pager]

Browses commit history as a topology graph (the default) or a flat list, with Change IDs and author class (human / agent). A <path> argument scopes the log to the commits that touched that file — or any file under it, for a directory.

Flag	Meaning
`--limit <n>`	Cap the number of commits shown (every output format).
`--entity agent\\|human`	Show only agent- or human-authored commits.
`--task-id <id>`	Show only commits an agent made under this task id (implies agent-authored).
`--format <fmt>`	`human` (default), `json`, `csv`, `template:<spec>` (e.g. `template:{change} {author} {message}`).
`--date relative\\|absolute`	How the human log shows each commit's time (default `relative`).
`--graph` / `--no-graph`	Render the topology graph (the default) or a plain flat list. The graph cannot be combined with the subsetting filters.
`--first-parent`	Walk only the first-parent line — "what shipped on this lane, in order".
`--all`	Seed the graph from every lane tip, not just HEAD.
`--oneline`	Compact one-line-per-commit view.
`--why`	Surface each commit's attested rationale (decision, confidence, rejected alternatives, dead ends).
`-S <string>` / `-G <regex>`	Pickaxe: only changes that added or removed the string / a line matching the regex.
`--session <chg>`	Render one change's attested session run record instead of the log.
`--descendants <chg>`	Show the changes built on top of `<chg>` — the forward direction of the log.
`--no-pager`	Do not pipe long output through a pager.

$ tovio log --entity agent --limit 5 --format json

Exit: 0.

`tovio diff`¶

Everyday · Phase 0.

tovio diff

Shows the working copy's changes since the last commit. It takes no arguments and no flags — the global flags (--json, --quiet) apply as they do everywhere.

The other two diffs are separate commands rather than modes of this one: tovio semantic diff for a function-level interface diff, and tovio behavioral diff for a behavioral snapshot.

Exit: 0.

`tovio undo` / `tovio redo`¶

undo: Everyday · Phase 0. redo: Advanced · Phase 0.

tovio undo [--to <op-id>]
tovio redo

tovio undo reverses the latest supported entry retained in the repository's local op-log, including recorded commit, sync, rebase, land, and lane-delete mutations. For sync it restores local state; it cannot recall objects or ref observations already received by peers. Irreversible maintenance such as authenticated obliteration and effects outside TOVIO are excluded.

Flag	Applies to	Meaning
`--to <op-id>`	`undo`	Rewind to just before the operation with this op-id, undoing every operation back to it in one step. The op-id appears in each `undo`/`redo` `--json` result and in `tovio explain undo`.

Neither command takes a count: undo reverses one step at a time (or several with --to), and redo replays the last undone operation.

$ tovio undo
✓ Undid: Add Dexcom G7 sync handler
  Redo with: `tovio redo`

Exit: 0 on success (TVO-OP-001 is the cataloged undo result). 19 (TVO-OP-002) when there is nothing to undo or redo; 2 (TVO-CLI-018) when --to names an op-id that is not a past undoable operation.

`tovio oplog`¶

Not implemented — no tier.

Not implemented: there is no tovio oplog command. The op-log itself exists — a local, never-synced history of every VCS operation that backs undo/redo — and is listed by tovio explain undo [--limit <n>] [--to <op-id>], which shows every operation, the undo/redo head, and the state undo would restore. Operation ids also appear in each undo/redo --json result and are consumed by tovio undo --to <op-id>.

`tovio change`¶

Everyday · Phase 0.

tovio change new [<description>] [--base <lane>] [--draft]
tovio change list [--stack] [--format <fmt>]
tovio change show [<change-id>] [--diff]
tovio change switch <change-id>
tovio change health <change-id>
tovio change describe <change-id> <msg>
tovio change split [<change-id>] --paths <glob>…
tovio change absorb [--dry-run]
tovio change rebase <change-id | start..tip> [--onto <lane-or-change>]
tovio change propose [<change-id>] --remote <host:port> [--target <lane>] [--cert <path>]
                     [--onto <prop-id>] [--sovereign] [--visibility inherit|restricted] [--reader <did>]…
tovio change pull <change-id>
tovio change watch <change-id> [--once] [--remote <host:port>] [--cert <path>]
tovio change notify <change-id>
tovio change promote <change-id>
tovio change abandon <change-id>
tovio change restore <change-id>

A change is your unit of work; a lane is a landing target, not a workspace. The Change ID survives every operation here. Every <change-id> is accepted as chg:<base32> or the bare base32 body — always the whole 26-character body; abbreviated prefixes are rejected.

Subcommand	Meaning
`new [<description>]`	Start a new change. With no `--base` it stacks on the current change; `--base <lane>` starts an independent track on that lane; `--draft` keeps it private (not landable until promoted).
`list`	List changes with each one's tip, description, and state. `--stack` also shows the read-only dependency (`pull`) edges; `--format` selects `human`, `json`, `csv`, or `template:<spec>`.
`show [<id>]`	Who / what / when / why / how: author and provenance, files changed, semantic delta, lane and state, "pulled by" edges, and best-effort local lineage. Defaults to the current change; `--diff` also renders the full content patch.
`switch <id>`	Move the working copy to a change; dirty work is three-way carried, never lost.
`health <id>`	Read-only: whether the change is conflict-free and landable.
`describe <id> <msg>`	Set or replace a change's local description.
`split [<id>] --paths <glob>…`	Carve the matching files into a fresh, landable ready sub-change and leave the rest as the remainder (which keeps this change's ID) — the way to do a partial land. At least one `--paths` is required; the change must be a lane tip.
`absorb [--dry-run]`	Fold each fixed-up file into the single unlanded ancestor that last touched it. Conservative: a file no ancestor (or several) touched stays put. `--dry-run` previews the routing.
`rebase <id> [--onto <rev>]`	Re-parent a change (or a `<start>..<tip>` range) onto `--onto` (default `main`), preserving every Change ID. Same-file overlaps store a conflict.
`propose [<id>] --remote <host:port>`	Open a proposal on the Forge (the PR equivalent) targeting `--target` (default `main`). `--onto <prop-id>` stacks it on an open parent proposal; `--sovereign` proposes by reference from a repository you control; `--visibility restricted` with `--reader <did>` narrows the audience within the repo's readers.
`pull <id>`	Record a teammate's change as a read-only dependency. Refuses a conflicted change; idempotent; materializes nothing.
`watch <id>`	Poll a Forge's event feed (`--remote`, cert-pinned) for events touching the change; resolves on a landed or resolved event. `--once` polls a single round.
`notify <id>`	Record a durable, never-synced notify-intent for the change; delivery is the Forge event feed's concern.
`promote <id>`	Promote a draft into a normal, landable change.
`abandon <id>`	Set a change aside — hidden from `change list` and not landable; its history is kept.
`restore <id>`	Recover an abandoned change.

$ tovio change health chg:a3f7b2h8xk0m9v2qp4r7t1nc5w
Change health - chg:a3f7b2h8xk0m9v2qp4r7t1nc5w
  tip commit: blake3:ce4273bd6f…
  conflicts:  none ✓
  staleness:  12 commit(s) behind main · 2 days old
  landable:   yes ✓

A partial land — land the ready files, keep the rest WIP — is tovio change split --paths <glob> then landing the ready sub-change. Never cherry-pick individual files out of a change.

Exit: 0 on success; 19 (TVO-OP-006) when no reachable commit carries the Change ID; 19 (TVO-OP-014/015/016) when rebase/split/absorb would cross a merge commit, the split partition is degenerate, or there is nothing to absorb; 1 (TVO-CONFLICT-004) when pull refuses a conflicted dependency.

`tovio amend`¶

Not implemented — no tier.

Not implemented: there is no tovio amend command. The shipped spelling is tovio commit --amend, which folds the working change into the last commit — with -m rewriting its message, without -m keeping it — and preserves the Change ID. There is no --intent flag anywhere in the CLI; the attested why is recorded by tovio resolve --why and read back with tovio log --why.

`tovio rebase`¶

Advanced · Phase 0.

tovio rebase [--onto <lane-or-change>]

Re-parents the current change and its stack onto a new base, producing new commit hashes while preserving every Change ID — the top-level form of tovio change rebase, which is the spelling that takes an explicit change or <start>..<tip> range. It takes no positional argument. Where content cannot auto-merge, conflicts are stored, not blocking. Undoable as a single tovio undo.

Flag	Meaning
`--onto <lane-or-change>`	The lane or `chg:` id to reparent onto. Default: `main`.

Exit: 0 (including when conflicts are stored).

`tovio squash`¶

Not implemented — no tier.

Not implemented: there is no tovio squash command and no change squash subcommand. The nearest shipped behaviour is tovio change absorb, which folds each fixed-up file into the single unlanded ancestor that last touched it.

`tovio reorder`¶

Not implemented — no tier.

Not implemented: there is no tovio reorder command and no tovio change equivalent. Reordering a stack is done today by rebasing its members with tovio change rebase.

`tovio blame`¶

Advanced.

tovio blame <file> [--first-parent] [--why] [--session]

Attribution by change, not by commit — points at the logical change that introduced a line, not the formatting commit that last touched it, so attribution survives history rewriting.

Flag	Meaning
`--first-parent`	Attribute along the first-parent line only — the lane-summary reading, where a merge stands in for the lane it integrated. The default walks every parent, crediting the change that wrote the line.
`--why`	After the attribution, surface each owning change's attested rationale. A sealed rationale is decrypted for a policy recipient and shown as a locked marker otherwise.
`--session`	After the attribution, surface each owning change's run record — the originating prompt and the ordered turns. An observed session is labelled UNATTESTED.

$ tovio blame src/integrations/cgm/dexcom.ts
chg:zzzx8k5m  export async function connect(): Promise<Session> {

Exit: 0.

`tovio lane`¶

Everyday · Phase 0.

tovio lane [<name>] [-d | --delete]

One command with no subcommands: tovio lane <name> creates a lane at the current tip, bare tovio lane lists them (the current one marked *), and tovio lane -d <name> deletes one. There is no lane create, no lane list, and no flag to branch from another revision — switch to the base first, then create.

Lanes are CRDT mutable pointers; creating and switching is O(1) and always safe offline. Deletion is fully undoable — deleting a lane never strands work.

Git-compat alias

tovio branch (and tovio br) are git-compat aliases for tovio lane, with the same arguments.

Argument	Meaning
`<name>`	Create a lane by this name at the current tip. Omit to list lanes.
`-d`, `--delete`	Delete the named lane (undoable).

$ tovio lane feature/cgm-sync
✓ Created lane feature/cgm-sync at blake3:ce4273bd6f…
  → Next: `tovio switch feature/cgm-sync` to work on it
  undo with `tovio undo`

$ tovio lane
  feature/cgm-sync  blake3:ce4273bd6f…
* main              blake3:ce4273bd6f…

Exit: 0 on success. 2 for an invalid name (TVO-CLI-005), a missing lane on -d (TVO-CLI-006), a name already taken (TVO-CLI-007), or -d on the current lane (TVO-CLI-009); 19 (TVO-OP-004) if there is no commit to branch from yet.

`tovio switch`¶

Everyday · Phase 0.

tovio switch <name-or-change-id>

Moves the working copy to another lane or directly to a change — a single-purpose replacement for Git's overloaded checkout. Dirty work is carried across by a three-way checkout rather than stashed, so nothing is lost; the summary line reports how many changes were carried and how many conflicted.

$ tovio switch feature/cgm-sync
✓ Switched to lane feature/cgm-sync  blake3:ce4273bd6f…
  materialized working copy · 1 carried change(s) · 0 conflict(s) · undo with `tovio undo`

Exit: 0 on success. 2 (TVO-CLI-006) for a missing lane.

`tovio land`¶

Everyday · Phase 0.

tovio land [<lane>…] [--into <target>] [--dry-run]
           [--rebase | --explain [--format human|json|html]]
           [--session-from <runtime|path> | --no-session]

Integrates one or more source lanes onto a target lane — the everyday "ship this work" verb. With no positional lane the source is the current lane; list two or more for a native N-way ("octopus") land. It advances <target> to include the source lane's work (a fast-forward, or a three-way merge), then automatically rebases every descendant change so a stack stays intact. The cascade is always synchronous. Change IDs are preserved throughout; the whole land, cascade included, is reversible as a single tovio undo.

Flag	Meaning
`--into <target>`	The target lane to land onto. Default: `main`.
`--rebase`	Integrate by rebasing the source onto the target instead of writing a merge commit — a linear mainline, at the cost of re-signing each change as the lander. Two-way only; never the default. Refused with `--explain`.
`--dry-run`	Assess the land without advancing any ref.
`--explain`	Print the full merge-process trace (base, per-file algebra, gates) before landing. With `--dry-run` it stops after the trace.
`--format human\\|json\\|html`	Renderer for the `--explain` trace, and only accepted with it. A global `--json` always wins.
`--session-from <runtime\\|path>`	Capture your agent transcript for the integration commit this land writes. Refused with `--rebase`, `--dry-run` or `--no-session`: those shapes author no commit of yours, and the parser rejects the combination rather than accept the flag and capture nothing.
`--no-session`	Do not capture an observed session for this land.

Protected lanes gate on conflict-free state

Landing onto a protected lane (e.g. main, release) requires a conflict-free change. tovio land refuses if the change's tree still contains unresolved conflicts, and runs all configured pre-land gates (proposal approval, required checks, write-policy clearance), refusing if any fails. The same gate is re-enforced at the Forge for propose / push, so it cannot be bypassed. Landing onto an unprotected lane may carry conflicts.

$ tovio land feature/cgm-sync --into main
✓ fast-forwarded main → feature/cgm-sync  blake3:a83d9291f5…
  same Change IDs — your work kept its identity · undo with `tovio undo`
  Rebased 2 descendant change(s) on 1 lane(s): feature/alerts  (Change IDs unchanged)

Exit: 0 on success (including when a descendant rebase stores a conflict). 1 (TVO-CONFLICT-003) when refused for landing a conflicted change onto a protected lane. 19 (TVO-OP-005) for a land precondition failure.

`tovio sync`¶

Everyday · Phase 3.

tovio sync [<remote> <repo>] [--cert <path>] [--push] [--pull] [--isolate]
tovio sync --watch [--once] [--interval <secs>]

The unified push + pull, for both human and always-on agent workflows. It is sparse by default and never "rejected": a divergent lane is reconciled on the lane into a two-parent merge (or a conflict-carrying commit), so "diverged history" is never an error and no tip is left off-lane. On an unprotected lane this is automatic; require_review lanes reconcile through their proposal/review path.

With no positional arguments it uses the origin saved at clone. --watch is a separate mode: it always uses the saved origin and always syncs both directions, so the parser refuses it together with <remote>, <repo>, --cert, --push, --pull or --isolate rather than silently ignoring them.

Flag	Meaning
`--cert <path>`	The relay's DER certificate. Omit to use the origin saved at clone.
`--push` / `--pull`	Restrict to one direction.
`--isolate`	Materialize conflicted dependency paths at their last-known-clean version so your tree builds; the conflict stays flagged and auto-updates on upstream resolution.
`--watch`	Keep syncing on an interval — pull, upstream-integrate, then a consent-gated push — until Ctrl-C.
`--once`	Requires `--watch`: run a single poll and return.
`--interval <secs>`	Requires `--watch`: seconds between polls (default `sync.auto.interval`, floored at 5).

Dependency-materialization gate

Conflict objects always download, but sync refuses to materialize a teammate's change that still has unresolved conflicts into your working tree as a dependency — it will not drop their conflict markers into your build. Use --isolate to build against the last-known-clean version, or tovio change notify <id> to wait. A conflict in your own stack never blocks you.

$ tovio sync
✓ Synced with origin  (received 4 changes, sent 1; refs merged)

Exit: 0 on success (a divergent sync reconciles on-lane and still exits 0). 17 (TVO-SYNC-001) for an unreachable peer (local work is never lost); 17 (TVO-SYNC-002) for a wire-protocol mismatch; 17 (TVO-SYNC-006) when a one-way --push is refused because the remote lane diverged (run a full tovio sync to reconcile); 1 (TVO-CONFLICT-004) when a conflicted dependency is gated.

`tovio fetch` / `tovio push`¶

Team · Phase 3.

tovio fetch [--complete] [--deepen <n>]
tovio push [<remote> <repo>] [--cert <path>]
tovio pull [<remote> <repo>] [--cert <path>] [--isolate]

push and pull are the one-direction primitives behind sync: push sends the objects and refs a relay lacks and, where a path has a write policy, includes the ABS proof; pull is its mirror, validating every object by re-hash before write. Run either with no arguments and it prints the git-compat hint instead of transferring anything. Most users should prefer sync.

fetch is not a third direction — it grows a partial clone along its two reversible axes, and takes no remote (it uses the promisor recorded at clone time).

Flag	Applies to	Meaning
`--complete`	`fetch`	Fetch every omitted object, returning the repository to a full local closure and clearing the promisor.
`--deepen <n>`	`fetch`	Extend a shallow (`clone --depth`) history by `n` more commits.
`--cert <path>`	`push`, `pull`	The relay's DER certificate to trust — the file `tovio serve` writes.
`--isolate`	`pull`	Materialize anyway when the dependency gate would refuse, holding each conflicted path at its most-recent conflict-free ancestor and pinning it so `status` flags the isolated build.

Exit: 0 on success; 17 (TVO-SYNC-001) for transport / protocol failures; 13 (TVO-PERM-002) for a write-policy rejection on push.

`tovio remote`¶

Advanced · Phase 3.

tovio remote add <name> <url> <repo> [--cert <path>]
tovio remote list
tovio remote show <name>
tovio remote remove <name>          # alias: rm

Manages remotes: a TOVIO relay (tovio://) or TOVIO-over-HTTPS (https://). add takes three positionals — the local name, the host URL, and the repository on it — plus --cert <path> to pin a native remote's DER certificate. show and list report the recorded configuration only.

Not implemented: there is no remote status, and no --bridge-mode flag. RemoteCmd is Add | List | Show | Remove (rm), and neither show nor list makes a network call — nothing currently reports remote reachability or the negotiated wire-protocol version. Git interop is the separate tovio git bridge command, not a remote mode.

Exit: 0 on success.

`tovio merge`¶

Not implemented — no tier.

Not implemented: there is no tovio merge command. Integration is tovio land, which folds one or more source lanes onto a target.

Whichever verb integrates, conflicts are stored, not blocking: a path that cannot auto-merge becomes a first-class conflict object and the integration completes. The repository stays fully operational with open conflicts, and the result is exit 0 (TVO-CONFLICT-001 is a success with follow-up, not an error).

`tovio conflicts` / `tovio resolve`¶

Everyday · Phase 0.

tovio conflicts
tovio resolve [<path>]
tovio resolve <path> <strategy> [--region <n>]
                     [--why <text> [--decision <text>] [--rejected "<option> :: <reason>"]…
                                   [--dead-end <text>]… [--confidence low|medium|high] [--ref <token>]…
                      | --rationale-ref <addr>]
                     [--session-from <runtime|path> | --no-session]

  <strategy> = --ours | --theirs | --base | --ai | --working-tree | --keep | --delete
             | --rename-to <path>

Conflicts are data, not errors. tovio conflicts takes no arguments and lists every open conflict in the current change with the command that resolves each. tovio resolve is addressed by path, not by a conflict id, and dispatches on the conflict's kind.

With no strategy flag on a terminal, resolve walks each open conflict interactively — a unified ours-vs-theirs diff per region and a per-region choice. No conflict markers ever reach your files, and no external editor is opened. Pass a <path> alone to walk just that one conflict. At most one strategy flag may be given.

The interactive walk reads your choice from the terminal, so it refuses when stdin is not interactive or output is --json/--quiet. Name a path and a strategy to script it.

Command / flag	Meaning
`conflicts`	List every open conflict in the current change and how to resolve each.
`resolve [<path>]`	Interactive resolution — every open conflict, or just the one at `<path>`.
`resolve <path> --ours` / `--theirs` / `--base`	Keep our side, their side, or the common ancestor.
`resolve <path> --ai`	Ask the configured resolver plugin to propose a resolution. With no resolver bound it declines.
`resolve <path> --working-tree`	Record the file's current on-disk bytes as the merged result — for a hand-merged file. Whole-file kinds only (content / add-add / rename-edit).
`resolve <path> --region <n>`	Record the choice for just the 0-based conflict region, in `merge3` order. Requires a strategy flag, and is refused with `--working-tree` — a whole-file merge has no per-region choice.
`resolve <path> --keep` / `--delete`	Keep the modified side, or accept the deletion, on a delete-modify conflict.
`resolve <path> --rename-to <path>`	Choose the target path for a rename-rename conflict.
`resolve <path> --why <text>`	Record why you resolved it, as an attested rationale on the resolving commit — read back with `tovio log --why`, and sealed automatically when the path is protected. Requires a strategy flag: the rationale rides the resolving commit, and the interactive walk authors none. `--decision`, `--rejected`, `--dead-end`, `--confidence` and `--ref` refine it and each require `--why`.
`resolve <path> --rationale-ref <addr>`	Link a pre-authored rationale object instead of writing one inline. Also requires a strategy flag; mutually exclusive with `--why` and its refinements.
`resolve <path> --session-from` / `--no-session`	Capture, or decline, the agent transcript for the resolving commit. A working-copy-only resolve writes no commit and so has no home for one.

A semantic conflict is an advisory warning, not a text merge; it lists the dependent changes whose references broke and does not block unless a protected lane requires the semantic check.

Exit: 0 on success — tovio conflicts exits 0 even with conflicts open. 1 (TVO-CONFLICT-002) when a resolution is rejected (already resolved, unparseable, or out of scope).

`tovio build-check`¶

Advanced · Phase 0.

tovio build-check [<lane>]

Verifies that a lane is conflict-free — its tip carries no unresolved conflict objects. Defaults to the current lane. A protected lane may require this to pass before you can land onto it.

This is the VCS-layer gate only: there is no configuration slot for a repository build or verify command, so today build-check never compiles or tests anything.

Exit: 0 = conflict-free. Non-zero lists the offending paths.

`tovio explain`¶

Advanced · Phase 0. Read-only.

tovio explain <lens> [args] [--format human|json|html]

Debug how a TOVIO subsystem reached its state — replay the decision read-only and render the reasoning instead of a one-line verdict. Ten lenses, each in three formats (terminal, --json with schema tovio.explain/1, and a self-contained HTML page). See the guide: Explain — ask TOVIO to explain itself.

Lens	Purpose
`tovio explain merge [<lane>] [--into <target>] [--commit <addr>]`	The merge-process debugger: merge base, per-file merge/conflict decisions, and the gate checklist. Prospective, or `--commit` to replay a landed merge.
`tovio explain lanes [<lane>…] [--limit <n>]`	A multi-lane swimlane timeline: lanes as rows, with fork and merge connectors.
`tovio explain sync [<lane>]`	CRDT ref-merge: each replica's HLC-stamped candidate, which won, and why.
`tovio explain deps <commit>`	The materialization gate (`TVO-CONFLICT-004`): the dependency relation, the path overlap, and what `--isolate` would derive.
`tovio explain rerere [<path>]`	Recorded-resolution replay: region-key matches, anchor collisions, and the version gate.
`tovio explain dag [<a>] [<b>]`	Ancestor sets, ahead/behind, the common ancestor(s), and generation numbers.
`tovio explain change <chg>`	Trace a Change ID across amend / rebase / squash / absorb.
`tovio explain semantic [<a>] [<b>] [--into <lane>]`	Symbol-graph diff (added / removed / changed) and the `semantic-check` gate.
`tovio explain plugin [--event <e>]`	Which lifecycle plugins are bound, advisory vs enforcing, and their filters.
`tovio explain undo [--limit <n>] [--to <op-id>]`	The op-log, the undo/redo head, and the snapshot diff `undo` would restore.

The merge lens is also a flag on the verbs you already use: tovio land … --explain (and --dry-run --explain to trace without landing) and tovio health --explain.

Exit: 0. explain is read-only — it never takes a lock or advances a ref.

`tovio policy`¶

Team · Phase 1.

tovio policy set <path-pattern> --read <expr> [--write <expr>]
tovio policy list
tovio policy show <path>
tovio policy remove <path-pattern>
tovio policy test <path> [--identity <identity.pub>] [--write]
tovio policy sign
tovio policy change-control <path-pattern> [--min-approvals <n>] [--reviewer <did>]…
                            [--required-checks <list>] [--remove]
tovio policy protect <lane-pattern> [--require-review] [--min-approvals <n>] [--reviewer <did>]…
                     [--required-checks <list>] [--remove]
tovio policy web-auth [--allow <mechanisms>] [--require-bridge-for <paths>]
tovio policy proposal-visibility …
tovio policy chunking … | signing … | audit … | hook …

Declares an access policy on a path. Once set, matching files are automatically encrypted at snapshot time so plaintext never lands in a tracked tree. The policy manifest is itself version-controlled and always clear-readable.

Subcommand	Meaning
`set <pattern> --read <expr> [--write <expr>]`	Declare read/write policy. `--read` takes a boolean attribute expression (e.g. `role=senior & clearance=secrets`) or `ANY` for a clear path; `--write` defaults to the read policy.
`list`	List every policy declaration.
`show <path>`	Show the effective policy for a path.
`remove <pattern>`	Remove the policy for an exact path glob.
`test <path>`	Evaluate offline whether an identity satisfies a path's effective policy. `--identity` takes a recipient's `identity.pub` and defaults to this repository's own; `--write` tests the write policy.
`sign`	Re-attest the working-copy policy manifest under the repository owner root. The recovery when a manifest is present but unattested — content is unchanged, so it is safe to re-run.
`change-control <pattern>`	Require an approved proposal for any change touching a path glob, on any lane. `--remove` deletes the rule.
`protect <pattern>`	Lane protection: require an approved, reviewed proposal to land on a lane. `--remove` deletes it.
`web-auth`	Which browser mechanisms may perform a mutating Forge web request, plus paths that mandate the local bridge.
`proposal-visibility`	Who may open a restricted-visibility proposal in this repository.
`chunking` / `signing` / `audit` / `hook`	The authenticated per-repository FastCDC policy, commit/protected-ref signature requirements, justification requirements, and enforcing plugin bindings.

$ tovio policy set "config/production/**" --read "role=senior & clearance=secrets" --write "role=staff | role=security"
✓ Policy set for config/production/**
  Files under config/production/** will be encrypted on the next commit.

Exit: 0 on success; 13 (TVO-PERM-007) if you are not the repository owner and so cannot alter policy.

`tovio access`¶

Team · Phase 1.

tovio access check <path> [--identity <identity.pub>] [--write]
tovio access request <path-pattern> [--write] [--attr <name=value>]… [--from <identity>]
tovio access requests
tovio access grant --identity <identity.pub> [--attr <name=value>]… [--code <code>]
tovio access list
tovio access revoke <did>

tovio access check is the diagnostic that every permission error points at. It names the policy, the subject, which attributes are satisfied, and the verdict — never a bare "denied". There is no access policy subcommand; policy declarations live under tovio policy.

Subcommand	Meaning
`check <path>`	Diagnose read (or `--write`) access, per attribute. `--identity` takes a recipient's `identity.pub` and defaults to this repository's own.
`request <pattern>`	Open a portable request to the repository Key Authority. `--attr name=value` is repeatable; `--from` requests on behalf of another public identity.
`requests`	List the pending portable access requests visible in this repository.
`grant --identity <pub>`	Enroll a recipient from their `identity.pub` and grant them attributes. `--attr` is repeatable; `--code` redeems a request code.
`list`	List enrolled recipients and their granted attributes.
`revoke <did>`	Remove a recipient and rotate the committed protected state to the reduced roster.

$ tovio access check config/production/api-keys.env
config/production/api-keys.env  (read policy: role=senior & clearance=secrets)
  subject: did:key:7b5cf5bf93… (repository owner)
  verdict: AUTHORIZED ✓

Exit: 0. check reports its verdict in the body and the --json result, not via the exit code.

`tovio review`¶

Team · Phase 3.

tovio review <change-id>
tovio review <change-id> (--approve | --request-changes) --proposal <prop-id> --remote <host:port>
                         [--cert <path>]

Renders a change's diff against its base, redacting what you cannot see: clear paths diff normally, a protected path you can decrypt shows its decrypted diff, and a protected path you cannot decrypt shows only a 🔒 not accessible to you marker and a coarse change indicator — never the plaintext or anything derived from it. It ends with a coverage summary. The argument is the change, not the proposal.

Without a decision flag it stays a local render. With one, it also submits the decision to the Forge, so --proposal and --remote become required. The reviewer is your signing identity — never a field you set — and there is no comment flag.

Approval is a pre-land gate: on a protected lane whose policy requires review, tovio land refuses until the proposal is approved, and --request-changes keeps it blocked until addressed.

Flag	Meaning
`--approve`	Submit an approve decision. Needs `--proposal` and `--remote`.
`--request-changes`	Submit a request-changes decision. Mutually exclusive with `--approve`.
`--proposal <prop-id>`	The Forge proposal (`prop:…`) the decision transitions.
`--remote <host:port>`	The Forge to submit to. The signed request rides pinned-cert TLS.
`--cert <path>`	The Forge's pinned DER certificate. Defaults to this repository's `.tovio/relay-cert.der`.

Exit: 0.

`tovio identity`¶

Team · Phase 1.

tovio identity show
tovio identity init
tovio identity connect --forge <host:port> --code <code> [--cert <path>] [--label <label>]
tovio identity authorize-device --account <account>

A repository has one cryptographic identity (Ed25519 signing + X25519 exchange, named by a did:key:…), not a list of them. In Simple Mode there is none at all; identity init provisions one and upgrades the repository to Team Mode.

Subcommand	Meaning
`show`	The DID and public keys, and whether the secret is sealed in the OS keychain.
`init`	Provision an identity for an existing Simple-Mode repository, upgrading it to Team.
`connect`	Link this device to a hosted-Forge account with a single-use pairing code.
`authorize-device`	Authorize adding another device to your hosted-Forge account.

Per-device keys under this identity are managed by tovio device (enroll / list / revoke).

Exit: 0.

`tovio key`¶

Team · Phase 1.

tovio key status
tovio key renew
tovio key rotate
tovio key export <file> --passphrase-file <path>
tovio key import <file> --passphrase-file <path>
tovio key recover --from <path>

Subcommand	Meaning
`status`	The attribute certificates this identity holds, with issuer, expiry, and validity.
`renew`	Renew the attribute certificates this identity issued, before they lapse — the recovery for expiry errors.
`rotate`	Rotate the identity / Key Authority key: re-issue claims, re-seal HEAD, then swap the key. Crash-resumable.
`export <file>`	Back up the root device secret to a portable, passphrase-encrypted file.
`import <file>`	Restore the root device from a backup, re-sealing it into this machine's OS keychain.
`recover --from <path>`	Recover after losing the identity key, using the recovery phrase generated at `init`.

There is no key sync.

Exit: 0 on success. 11 (TVO-KEY-001/002/003/005) for expiry, missing material, a wrong-identity backup, or a failed rotation journal.

`tovio agent`¶

Team · Phase 2.

tovio agent new <name> --model <model> --task <task> [--expires-in <hours>] [--can-delegate]
tovio agent list
tovio agent show <token-id>
tovio agent token <token-id>
tovio agent renew <token-id> [--expires-in <hours>]
tovio agent revoke <token-id>
tovio agent resume <target>
tovio agent backfill <target> --session-from <path>
tovio agent abandon <branch>
tovio agent promote <name> [--onto <lane>]
tovio agent intent declare [<globs>…] --token <token-id> [--ttl <secs>] [--lease] [--force]
tovio agent intent check [<paths>…]
tovio agent intent list
tovio agent session export <token-id> <file> --passphrase-file <path> [--expires-in <hours>]
tovio agent session oidc <remote> <repo-id> --policy <p> --id-token-file <f> …
tovio agent issuer-policy …

tovio agent new issues a tovio-capability-v1 capability token signed by the current human identity. --model and --task are both required; --expires-in is in hours and defaults to 24.

Token defaults (capability/issuance.rs): path_scope = ** minus every policy-protected path; branch_scope = agent/<name>/**; secret_clearance = false; allowed_ops = read, commit, amend, branch:create, relay:fetch, relay:push, conflict:resolve; denied_ops = obliterate, policy:modify, tag:create, tag:force, sub-token:issue. There is no flag to narrow the scope or grant clearance at issuance.

Subcommand	Meaning
`new <name>`	Issue a token. `--can-delegate` grants the right to issue narrower sub-tokens (off by default).
`list`	The active agent sessions: their scope, expiry, and status.
`show <token-id>`	Inspect an issued token.
`token <token-id>`	Print the token in machine form, for handing to the agent / MCP client.
`renew <token-id>`	Re-issue with a fresh expiry — a deliberate re-issue, never an extension.
`revoke <token-id>`	Revoke a token, and with it any tokens delegated from it.
`resume <target>`	Rebuild an earlier change's working context so another agent, or a person, can pick it up.
`backfill <target>`	Associate an existing agent transcript with a change that already exists.
`abandon <branch>`	Tombstone an `agent/<name>/…` branch; its objects stay reachable, none are orphaned.
`promote <name>`	Accept an agent's work: land its branch onto `--onto`, then tear the branch down.
`intent declare` / `check` / `list`	Non-blocking, TTL'd coordination signals — "is another agent working here?". `declare` needs `--token`; `--ttl` is in seconds (default 3600). `--lease` asks for an advisory lease, so a peer entering those globs is warned harder and — only where the repository's coordination policy requires it — soft-blocked; `--force` proceeds through someone else's lease.
`session export` / `session oidc`	Prepare a finite, repository-bound session for a CI or hosted runner.
`issuer-policy`	Sign an exact OIDC trust-domain policy for short-lived runner enrollment.

There is no agent delegate subcommand: delegation is a right granted at issuance with --can-delegate, and the sub-token is minted by the agent itself.

$ tovio agent new claude-code --model "anthropic:claude-opus-4-8" --task "CGM sync handler" --expires-in 2

Agents are never granted destructive operations

obliterate, policy:modify, tag:create and tag:force are denied on every token this command issues. A human must perform those. Widening a sub-token's scope beyond its parent is refused.

Exit: 0 on success. 13 (TVO-TOKEN-001…007) for scope / op / validity / delegation failures; 11 (TVO-TOKEN-008) when run in a Simple repo with no identity.

`tovio audit`¶

Team · Phase 1.

tovio audit log [--format <fmt>]
tovio audit summary [--last <duration>]
tovio audit show (--object <hash> | --token <token-id>)
tovio audit verify
tovio audit graph <target> [--depth <n>] [--format <fmt>]
tovio audit export [<target>] --format json|csv|cef|syslog|prov-json|in-toto
                   [--output <path>] [--depth <n>] [--tls <host:port> [--server-name <dns>] [--cert <path>]]
tovio audit archive
tovio audit fetch <actor> --remote <host:port> [--cert <path>]

Subcommand	Meaning
`log`	The audit entries, newest first. `--format` selects `human`, `json`, `csv`, or `template:<spec>`.
`summary [--last <dur>]`	A rollup by identity and event.
`show`	The records for one object or one token. Exactly one of `--object` / `--token` is required.
`verify`	Verify the chain offline: every entry's Ed25519 signature plus the per-actor hash links.
`graph <target>`	The lineage graph for a `chg:` id, commit address, `task:<id>` or `session:<id>` — human to token to agent to model to change to signature. A sealed node this reader cannot decrypt renders as a locked marker, never omitted.
`export`	Export signed audit records for archive or SIEM ingestion. `--format` selects a signed-chain rendering (`json`, `csv`, `cef`, `syslog`) or a lineage export of `<target>` (`prov-json`, `in-toto`, which also honour `--depth`). `--output` writes a file atomically; `--tls <host:port>` delivers to a collector, with `--server-name` overriding the certificate's DNS name and `--cert` pinning its DER certificate.
`archive`	Move entries older than the retention window into an immutable archive behind a signed checkpoint.
`fetch <actor>`	Fetch and verify a remote actor's Forge audit chain over a signed, cert-pinned connection.

The planned log --since/--path/--identity/--agent filters and a per-principal zero-read denial rollup are not implemented yet. Use summary --last and show --object/--token to narrow the current output.

Exit: 0 on success; 7 if verify finds the log corrupt.

`tovio behavioral`¶

Advanced · Phase 2+.

tovio behavioral snapshot [--model-id <id>] [--prompts <text|path>] [--tools <text|path>]
                          [--memory <text|path>] [--retrieval <text|path>]
                          [--policy-version <label>]
tovio behavioral list
tovio behavioral diff <commit-a> <commit-b>
tovio behavioral rollback <commit>

Versions an AI system's full behavioral surface — model, prompts, tools, memory, guardrails — diffable independently of code.

Subcommand	Meaning
`snapshot [...]`	Capture a behavioral snapshot and link it to HEAD.
`list`	List snapshots.
`diff <a> <b>`	Compare two commits' behavioral surfaces and report which fields changed.
`rollback <commit>`	Roll the behavioral surface back to an earlier commit's, without touching the code or tree.

Every snapshot descriptor is optional; an omitted one hashes the empty string, so a partial snapshot is well-defined and reproducible.

`snapshot` flag	Meaning
`--model-id <id>`	The model the system runs, e.g. `anthropic:claude-opus-4-8`. Hashed.
`--prompts <text\\|path>`	The prompt template surface. Hashed.
`--tools <text\\|path>`	The tool manifest. Hashed.
`--memory <text\\|path>`	The memory configuration. Hashed.
`--retrieval <text\\|path>`	The retrieval configuration. Hashed.
`--policy-version <label>`	The guardrail version label in force. Recorded verbatim, not hashed.

Each of the five hashed descriptors accepts either a literal string or a path whose contents are read and hashed. Hashing happens at the CLI edge so that tovio-core stays I/O-free.

Exit: 0.

`tovio semantic`¶

Advanced · Phase 2+.

tovio semantic find-def <moniker>
tovio semantic find-refs <moniker>
tovio semantic callers <moniker>
tovio semantic tested-by <moniker>
tovio semantic types <moniker>
tovio semantic search <query> [--limit <n>]
tovio semantic impact [<moniker>] [--depth <n>]
tovio semantic diff [<old>] [<new>]

Queries the optional semantic symbol graph: function-level diffs and structural queries. Optional and additive — TOVIO is fully functional without it.

Subcommand	Meaning
`find-def <moniker>`	Resolve a symbol's definition(s) by SCIP descriptor moniker.
`find-refs <moniker>`	Every reference to the symbol.
`callers <moniker>`	Callers of the symbol.
`tested-by <moniker>`	Tests covering the symbol.
`types <moniker>`	The symbol's supertypes.
`search <query> [--limit <n>]`	Ranked search over descriptor names. Default 20, capped at 500.
`impact [<moniker>] [--depth <n>]`	Reverse dependency closure. Omit the moniker to seed from this change's removed/changed symbols. Default depth 3.
`diff [<old>] [<new>]`	Symbol-graph delta. Defaults to HEAD's first parent versus HEAD.

Exit: 0.

`tovio obliterate`¶

Advanced · Phase 1+.

tovio obliterate <object-hash> --confirm "obliterate <object-hash>" [--reason <text>]

Permanent and irreversible

Obliteration is the permanent, auditable removal of an object's payload — there is no undo. The address survives as a typed tombstone (reads return TVO-STORE-002, never a 404). It requires the full confirmation phrase typed verbatim — --confirm "obliterate <hash>" — and never accepts a bare --yes. This is a human-only operation — obliterate is denied on every capability token the CLI issues.

Flag	Meaning
`--confirm "obliterate <hash>"`	The exact confirmation phrase. Required, verbatim.
`--reason <text>`	A reason, preserved in the signed tombstone and the audit log.

$ tovio obliterate blake3:5d20ab --confirm "obliterate blake3:5d20ab" --reason "Leaked credential; removed per policy"
✓ Obliterated blake3:5d20ab. A tombstone remains; the action is recorded in the audit log.

Exit: 0 on success. 2 (TVO-CLI-002) when the confirmation phrase is missing or a bare --yes was supplied.

`tovio git`¶

Advanced · import Phase 0; export/bridge Phase 3.

tovio git import [<source>] [--anonymize] [--mailmap <path>] [--no-repack] [--no-ignore-translate]
tovio git export <target-dir>
tovio git bridge <remote> [--bidirectional] [--watch [<secs>]]
tovio git setup <host> [--local]

Subcommand	Meaning
`import [<source>]`	Pull a Git repo's history and branches into this repository. `--anonymize` strips author identities, `--mailmap` applies a mailmap, `--no-repack` skips the post-import repack, `--no-ignore-translate` leaves `.gitignore` untranslated.
`export <target-dir>`	Write this repository's history and branches into a fresh local Git repository — a new or empty directory, never clobbered. Change IDs and agent provenance ride as commit-message trailers; protected paths export ciphertext-only. A lossy interop view, not a round-trip.
`bridge <remote>`	Run one safe two-way cycle: Git `refs/heads/X` → `git/<remote-id>/X`; a TOVIO lane `X` → `refs/heads/tovio/X`. Never force-pushes. `--bidirectional` is the explicit consent to exchange both directions; `--watch [<secs>]` repeats in the foreground (default 60s).
`setup <host>`	Point your `git` client at a TOVIO Forge over HTTPS: read a capability token from stdin, seal it in the OS keychain, and wire git's credential helper. `--local` writes to this repository instead of your global git config.

The bridge uses the installed Git credential stack, persists its per-remote hash/address map atomically, runs non-interactively, and times each Git operation out after 120 seconds (commands/git_bridge.rs). Rerun the command for another cycle, or use --watch.

There is no tovio migrate alias — the import spelling is tovio git import.

Exit: 0 on success. 21 (TVO-MIG-001/002/003/004) for a lossless-import conflict, non-fresh target, empty source, or bridge transport/credential/timeout/ref rejection.

`tovio fsck` / `gc` / `info` / `version`¶

Advanced · Phase 0.

tovio fsck [--strict] [--repair] [--fix-ignores]
tovio gc [--dry-run] [--auto] [--repack | --explode | --aggressive]

Command	Meaning
`fsck`	Re-hash objects and report corruption. `--strict` promotes advisory warnings to failures, `--repair` attempts recovery, and `--fix-ignores` repairs `.tovioignore` hygiene findings.
`gc`	Garbage-collect unreferenced objects. `--dry-run` reports what would be reclaimed; `--auto` runs only if the store warrants it; the three packing modes are mutually exclusive.

Not implemented: tovio info, tovio version, and fsck --object do not exist. There is no Info or Version variant in the Cmd enum, and Cmd::Fsck takes no object address. A live binary answers tovio version with error: unrecognized subcommand 'version'.

Use tovio --version — a global flag, not a subcommand — for the version, and tovio status for the repository summary. To narrow an integrity check to one address, use tovio audit show --object <hash>, which is real.

Exit: 0 when clean; 7 (TVO-STORE-001) when fsck finds corruption.

`tovio show`¶

Not implemented — no tier.

Not implemented: there is no Show variant in the Cmd enum, so tovio show, --verify and --tombstone do not exist.

The shipped ways to inspect an object by address are tovio cat for content and tovio audit show --object <hash> for its records. An obliterated object reports itself through TVO-STORE-002 on read, rather than through a dedicated flag.

`tovio mcp serve`¶

Advanced · Phase 2.

tovio mcp serve [--transport stdio|http] [--port <port>] [--bind <host>] [--token <capability-token>]

This command is registered by tovio-cli and launches the independently packaged tovio-mcp-server. The server executable must be installed on PATH, or selected with TOVIO_MCP_SERVER_BIN. The npm packages are publish-ready but not publicly published.

Every tool call is validated against the bound capability token; the server never registers obliterate, policy:modify, or key-management tools. Stdio is the default. Supplying --port or --bind implies Streamable HTTP, which defaults to loopback and requires a bearer secret for a non-loopback bind.

Flag	Meaning
`--transport <stdio\\|http>`	Select the protocol transport.
`--port <port>`	Streamable-HTTP port; defaults to 7744.
`--bind <host>`	Streamable-HTTP bind host; defaults to `127.0.0.1`.
`--token <capability-token>`	The capability token scoping the session.

Exit: 0 after a clean server exit; non-zero on launch or server failure.

`tovio relay serve`¶

Team · Phase 3.

tovio serve [--addr <host:port>]

Not implemented: there is no tovio relay noun, and no --port / --bind flags. Serving is tovio serve, documented here, which takes a single --addr.

Serves this repository to other machines over TLS — clone, fetch and push — with your permission policy enforced. It stores and serves objects, verifies write policies, records the audit log, and holds policy-protected payloads as ciphertext without recipient secrets. It remains an operational, metadata, write-policy, and availability trust boundary.

Flag	Meaning
`--addr <host:port>`	The listen address. Default `127.0.0.1:7743` — loopback, not `0.0.0.0`.

Exit: 0 while running; non-zero on a bind failure.

`tovio lock` / `tovio locks`¶

Team · Phase 3.

tovio lock <path> --ttl <duration> [--exclusive | --advisory] [--reason <text>]
tovio lock acquire <path> --ttl <duration> [--exclusive | --advisory] [--reason <text>]
tovio lock list
tovio lock release <path>

Exclusive / advisory locks for unmergeable binary paths. Only policy-declared lockable paths can be locked, and --ttl is required — there is no perpetual lock. It takes a duration such as 30m, 1h or 2d, and the lock auto-releases when it expires.

Command / flag	Meaning
`lock <path> --ttl <duration>`	Acquire a lock. The bare form of `lock acquire`. `--exclusive` / `--advisory` select the kind; give neither and the lock takes the kind the policy declares.
`lock list`	The local last-known view of active locks. Expired locks are dropped on read.
`lock release <path>`	Release your lock. Idempotent — releasing an unheld path succeeds.

tovio unlock <path> and tovio locks are deprecated hidden aliases for lock release and lock list; each prints a one-line stderr note and then runs the canonical command verbatim. There is no locks break — an operator force-releases a Forge grant with tovio forge lock.

The land gate is holder-agnostic

A land or push that finds an exclusive-lockable path edited divergently on both sides is refused, because a binary cannot merge into a content conflict and the later write would be lost. It is refused whoever holds the lock: no land or push path reads a lock store or a holder yet, so a lock held by someone else does not block your write. lock list is this clone's last-known view; a Forge is the authoritative arbiter of grants.

Exit: 0 on success. 13 (TVO-LOCK-001) when a path is already locked, and 13 (TVO-LOCK-002) when a land or push is refused on a diverged exclusive-lockable path.

`tovio meta`¶

Advanced · Phase 3+.

tovio meta create <name> [--atomic | --sequenced]
tovio meta attach <meta> <change-id> [--repo <r>] [--forge <host:port>] [--cert <path>] [--target <lane>]
tovio meta show <meta>
tovio meta list
tovio meta land <meta>
tovio meta resume <meta>

Groups changes across repositories to land atomically or sequenced. Each member passes its own repo's pre-land gates; atomic = all-or-none. The strategy is chosen at create, not at land.

Subcommand	Meaning
`create <name>`	Create an empty meta-change. `--atomic` is the default; `--sequenced` lands members in attachment order.
`attach <meta> <change-id>`	Attach a member change by its stable Change ID.
`show <meta>`	The strategy, the state, and each member's landability.
`list`	The meta-changes recorded here: name, strategy, state, member count.
`land <meta>`	Run the PREPARE and land sequence. An atomic meta completes PREPARE for every member before any COMMIT begins.
`resume <meta>`	Re-attempt the gate over the members a `partially_landed` meta has not landed yet.

Exit: 0 on success; non-zero if any member's pre-land gate fails (atomic = all-or-none).

`tovio forge`¶

Team · Phase 3+.

tovio forge lock|webhook|proposal|check|user|policy <…>
tovio forge provider|federation <…>   # hosted administration; session + enrolled device required

Operates a running Forge over its authenticated HTTP surface: users, repositories, organization policies, webhooks, and locks. Offline whole-root backup and restore deliberately live on the host-operator binary instead:

tovio-forge backup <destination> [--root <forge-root>]
tovio-forge restore <source> [--root <cold-forge-root>]

The Forge also serves GET /health and GET /metrics. Administrative mutations are authorized and audit-logged at the server edge; backup/restore requires host filesystem authority and never travels through the collaboration API.

Exit: 0 on success; 13 (TVO-PERM) without role=forge-admin.

`tovio help`¶

Everyday · Phase 0.

tovio help [<command>] [--team] [--advanced] [--all]

With no argument, lists only the 17 Everyday commands and a discovery footer pointing to the gated surfaces — showing the full 70-plus-command surface on first run is a documented adoption killer.

Flag	Meaning
`--team`	Reveal the Team tier.
`--advanced`	Reveal the Advanced tier.
`--all`	Reveal the entire surface.
(none) `<command>`	`tovio help <command>` prints full per-command help regardless of tier.

Exit: 0.

Other commands¶

The sections above cover the everyday loop and the commands whose flags need explaining. The rest of the surface is listed here — together they are the whole Cmd enum. Run tovio help <command> for the full per-command help, or tovio help --all for the tiered index.

Command	Tier	What it does
`tovio mv <from> <to>` (alias `rename`)	Everyday	Rename or move a tracked file, recording the move explicitly — regardless of similarity, and as one undoable operation.
`tovio health`	Everyday	Whether the current lane is clean, landable, and how stale. `--explain` traces the merge.
`tovio restore <file>`	Advanced	Discard working-copy edits to a file, resetting it to its last committed version.
`tovio tag [<name>] [<commit>]`	Advanced	Create, list, or (with `--force`) move an immutable tag.
`tovio cat <path>`	Advanced	Print a committed file's contents, decrypting it where you hold a reading key. `--side` reads one side of a materialized conflict, `--at` reads another revision, `--token` reads as an agent.
`tovio grep <pattern> [<rev>]`	Advanced	Search file contents at a revision, decrypting protected files you hold a key for. `-F`, `-i` and `--path` narrow it. To search history, use `tovio log -S` / `-G`.
`tovio materialize [<commit>]`	Advanced	Check a commit's tree out into the working copy. `--isolate` builds gated conflicted paths at their last-known-clean version.
`tovio cherry-pick <revs>…`	Advanced	Port or backport changes onto another lane, keeping every Change ID.
`tovio revert <revs>…`	Advanced	Mint a new forward change that inverts a landed change, leaving history intact.
`tovio bisect <verb>`	Advanced	Binary-search history for the change that introduced a regression: `start`, `good`, `bad`, `skip`, `run`, `status`, `reset`.
`tovio sparse <verb>`	Advanced	Declare and check out a cone of directories — the way to work a huge monorepo without materializing it: `set`, `add`, `list`, `clear`, `preview`, `checkout`.
`tovio fsmonitor <verb>`	Advanced	The filesystem-monitor daemon that makes change detection O(touched): `start`, `stop`, `status`, `query`.
`tovio autosync <verb>`	Advanced	Opportunistic auto-sync plumbing: `tick`, `status`, `upstream`. Not an everyday verb.
`tovio ci <verb>`	Advanced	Imported-CI inspection: `check` classifies each workflow's jobs on TOVIO compute, `compile` builds config-as-code pipelines.
`tovio plugin <verb>`	Advanced	Sandboxed lifecycle plugins — the capability-scoped alternative to shell hooks: `install`, `trust`, `list`, `bind`, `run`, `doctor` and more.
`tovio config <verb>`	Advanced	Repository preferences: `get`, `set`, `unset`, `list`, plus `secret` for a sealed AI-provider credential.
`tovio completions <shell>`	Advanced	Print a shell completion script.
`tovio device <verb>`	Team	Per-device keys of this identity: `enroll`, `approve`, `list`, `revoke`.
`tovio issue <verb>`	Team	The native Forge issue tracker: `create`, `list`, `view`, `comment`, `close`, `reopen`, `edit`, `label`, `assign`, `link`.
`tovio release <verb>`	Team	Releases and their downloadable assets on a Forge: `create`, `list`, `show`, `edit`, `publish`, `delete`, `asset`.
`tovio web-bridge --allow-origin <origin> [--forge <address>]`	Advanced	The local-agent web bridge — relays a browser's mutating requests to one Forge under this repository's keychain identity. Loopback-only. In a clone of a hosted repository `--forge` defaults to the `origin`, the repository's own address; a native Forge (and a repository with no origin) names it: `--forge <host:port>`, the Forge's web address. A bridge on the defaulted Forge forwards no account session, so administration needs an explicit `--forge`.
`tovio web-session authorize <pubkey>`	Advanced	Authorize a browser's ephemeral web-session public key as a principal (default and maximum TTL 900s).

Git-compat commands¶

These exist for muscle memory. Each does the right TOVIO thing (or explains what to do instead) and prints one gentle note to stderr, never into --json stdout. They are hidden from tovio help.

Git spelling	What TOVIO does
`tovio add [<paths>…]`	Nothing to stage — explains that the working copy is always tracked, and points at `tovio status`.
`tovio branch [<name>] [-d]` (alias `br`)	Runs `tovio lane` with the same arguments.
`tovio checkout [-b] <name>`	Runs `tovio switch`; `-b` creates the lane first.
`tovio stash`	Explains that your work is already a tracked change, and points at `tovio status`.
`tovio reset`	Points at `tovio undo`.
`tovio push` / `tovio pull` with no arguments	Prints the explicit form to use, and notes that `tovio sync` does both in one.
`tovio mv` as `tovio rename`	The same command under its Git-ish name.

Silence the notes with tovio config set compat.git.notes off (or TOVIO_GIT_COMPAT_NOTES=off).

Command reference¶

tovio init¶

tovio quickstart¶

tovio clone¶

tovio status¶

tovio commit¶

tovio log¶

tovio diff¶

tovio undo / tovio redo¶

tovio oplog¶

tovio change¶

tovio amend¶

tovio rebase¶

tovio squash¶

tovio reorder¶

tovio blame¶

tovio lane¶

tovio switch¶

tovio land¶

tovio sync¶

tovio fetch / tovio push¶

tovio remote¶

tovio merge¶

tovio conflicts / tovio resolve¶

tovio build-check¶

tovio explain¶

tovio policy¶

tovio access¶

tovio review¶

tovio identity¶

tovio key¶

tovio agent¶

tovio audit¶

tovio behavioral¶

tovio semantic¶

tovio obliterate¶

tovio git¶

tovio fsck / gc / info / version¶

tovio show¶

tovio mcp serve¶

tovio relay serve¶

tovio lock / tovio locks¶

tovio meta¶

tovio forge¶

tovio help¶

Other commands¶

Git-compat commands¶

See also¶

`tovio init`¶

`tovio quickstart`¶

`tovio clone`¶

`tovio status`¶

`tovio commit`¶

`tovio log`¶

`tovio diff`¶

`tovio undo` / `tovio redo`¶

`tovio oplog`¶

`tovio change`¶

`tovio amend`¶

`tovio rebase`¶

`tovio squash`¶

`tovio reorder`¶

`tovio blame`¶

`tovio lane`¶

`tovio switch`¶

`tovio land`¶

`tovio sync`¶

`tovio fetch` / `tovio push`¶

`tovio remote`¶

`tovio merge`¶

`tovio conflicts` / `tovio resolve`¶

`tovio build-check`¶

`tovio explain`¶

`tovio policy`¶

`tovio access`¶

`tovio review`¶

`tovio identity`¶

`tovio key`¶

`tovio agent`¶

`tovio audit`¶

`tovio behavioral`¶

`tovio semantic`¶

`tovio obliterate`¶

`tovio git`¶

`tovio fsck` / `gc` / `info` / `version`¶

`tovio show`¶

`tovio mcp serve`¶

`tovio relay serve`¶

`tovio lock` / `tovio locks`¶

`tovio meta`¶

`tovio forge`¶

`tovio help`¶