Use TOVIO from a script

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

These shapes are a contract, not debug output — the editor extensions and the SDK are built on them, and they follow the project's deprecation policy.

One envelope, two halves

Every --json invocation prints exactly one object to stdout. Success puts the payload under a top-level result; failure puts it under error. Test for which key is present; do not test the exit code first and then guess.

{ "result": { "branch": "main", "change": null, "changed": 2, … } }

The global flags that exist

Supplying both --json and --quiet is a usage error, not a silent precedence pick. There is no global --no-color and no -C: set NO_COLOR in the environment instead, and change directory yourself.

Other renderers

The commands that produce a data set — log, audit log, audit graph, change list — also take --format, which accepts human, json, csv, and template:<spec>:

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

--json and --format json produce identical output. Commands that are not data sets — status, diff, conflicts — take --json only; --format there is a usage error.

Exit codes are coarse on purpose

There is one exit code per area class, not one per error code, so a script can branch on category cheaply while the precise code lives in the JSON. Do not hard-code the numbers: read exit_class and code from the error object instead, and see the error-handling article for the shape.

One value is worth knowing by heart: 0. A created conflict exits 0, and tovio conflicts exits 0 whether or not it found any — a conflict is data you resolve, not a failed operation.

Do not guess at retryability

The error object carries an explicit retryability field. Read it. Inferring retryability from the area prefix or the numeric exit is specifically ruled out by the contract, because the mapping is not one-to-one and will change under you.

Nothing extra appears in it

--json and --quiet output never gains feedback prompts, celebration, glyphs, or marketing text — those are reserved for interactive human output. What you parse today is what you parse later.

Useful environment variables

When to move up to the SDK

Once you are doing more than a handful of commands, or need write sessions and structured commit rationale, the Node SDK is a typed API over the same engine rather than a wrapper around a subprocess.