Get machine-readable output

--json is a global flag — every command accepts it, and the shape is a stable contract rather than a debug dump. The editor extensions and the SDK are built on it.

tovio status --jsontovio log --format jsontovio change list --format jsontovio undo --json

The four global flags

--json and --quiet select mutually exclusive output modes, so passing both is rejected up front with TVO-CLI-017 (exit 2) rather than silently picking one.

Tabular output

tovio log --format csvtovio log --format 'template:{change} {message}'

The data-producing commands (log, change list, audit log) also take csv and template:<spec>. CSV is RFC-4180-style with a header row; a template substitutes {column} per row, expands an unknown column to nothing, and treats {{ / }} as literal braces. An unrecognised format value is TVO-CLI-016.

Exit codes carry meaning

Exit codes are deliberately coarse — one per error class, not one per code — so a script can branch on category (a usage mistake, a permission denial, a storage problem, a sync failure) while the precise code lives in the JSON. 0 is success, and an open conflict is success: conflicts are data, so tovio conflicts and a conflict-creating land both exit 0.

The authoritative class-to-number mapping lives in the error reference on tovio.dev, alongside every code. Read it from there rather than inferring it — a handful of legacy codes carry more than one exit class for compatibility, so a code alone does not determine the number.

Every error carries a TVO-<AREA>-<NNN> code in both the human and the machine-readable form, and the JSON error object echoes exit_code for consumers that are not a process. Branch on code when you need precision and on the exit status when you need a category.

What is deliberately absent — and the one exception

--json and --quiet suppress celebration lines and next-step hints, so stdout carries the contract and nothing else. Interactivity never leaks into a machine path either: a command that would prompt a human refuses instead when there is no terminal.

The exception is the git-compat note. tovio add, tovio stash, tovio reset, tovio checkout and tovio branch each write a one-line “TOVIO calls this…” note to stderr, and that note is not gated on the output mode — it prints under --json and under --quiet alike. It is gated only by configuration:

tovio config set compat.git.notes off# or, per invocation:TOVIO_GIT_COMPAT_NOTES=off tovio add .

Turn it off in any pipeline that merges stderr into stdout.

Higher-level automation

For anything beyond a few commands, the Node SDK gives a typed API over the same engine, including write sessions and structured commit rationale. See the automation collection.