Commit your work

tovio commit, its full flag set, and why there is nothing to stage first.

Written By Dustin

Last updated 29 minutes ago

tovio commit -m "what changed and why"

That is the whole operation. No add, no index — your working copy was already being snapshotted into the current change. tovio add exists only as a git-compat alias: it is a deliberate no-op that prints a note and points you at tovio status.

The message

Omit -m on an interactive terminal and TOVIO prompts you for the message. With --json or --quiet, or with no terminal at all, -m is required: a missing message is TVO-CLI-019 (“This commit needs a message”, exit 2). An empty message at the interactive prompt is the same refusal.

If nothing has changed there is nothing to snapshot, and the commit is refused with TVO-OP-003 (“Nothing to commit”, exit 19). Run tovio status to see why.

Every flag

FlagWhat it does
-m, --message <msg>The commit message.
--amendFold the working change into the last commit instead of creating a new one. Keeps the change id.
--token <id>Commit as an agent under a capability token. Scope is enforced on the changed paths before anything is sealed.
--prompt <text>The initiating instruction; its BLAKE3 is recorded in provenance. Requires --token — clap rejects it alone.
--session-from <runtime|path>Capture the agent transcript from a named runtime (claude-code, codex, open-transcript) or a file, instead of discovering one.
--no-sessionDecline transcript capture for this commit, even if one is discoverable.
--no-generateSkip the opt-in config-as-code regeneration (ci.generate=on) for this commit.

What a commit records

A content-addressed snapshot, the author, the time and your message — plus, on an agent commit, the full provenance (model, task id, token, delegation chain, authorizing human).

An attested rationale — the object tovio log --why reads back — is not authored by tovio commit; there is no --why flag on it. Rationales are written by the Node SDK write session and the MCP edge when an agent commits, and by tovio resolve --why when you resolve a conflict. Reading them is universal; writing them is a property of the authoring surface.

If paths are protected

Content covered by a policy is encrypted at snapshot time, before it is written, so plaintext never lands in the tracked tree. If you are not entitled to write a protected path, the commit is refused before anything is sealed with TVO-PERM-002 (write-policy / ABS rejection, exit 13). An agent whose token does not cover a changed path is refused earlier still, at the scope stage, with TVO-TOKEN-001.

Committing as an agent

tovio commit --token <id> --prompt "the instruction given" -m "..."

Transcript capture is on by default and produces an observed session: self-reported and explicitly unattested. It is refused if provenance.observed_capture is off (TVO-PROV-008) or if the transcript fails the mandatory secret scan (TVO-PROV-007).