Global flags¶

These flags and conventions apply uniformly to every tovio command — they are the contract a script or agent can rely on across the whole surface. For per-command flags, see the command reference.

Invocation grammar¶

tovio [<global-flags>] <command> [<subcommand>] [<args>] [<command-flags>]

Commands with multiple operations use a <command> <subcommand> noun-verb shape (tovio change show, tovio agent new, tovio policy set). Single-purpose commands take no subcommand (tovio commit, tovio status, tovio undo). A global flag is accepted anywhere on the line — before or after the command — because it is declared globally rather than per-command.

Output modes¶

Every command supports three mutually exclusive output modes. The default is human TTY output.

Mode	Flag	Behavior
Default	(none)	Human-readable, colored, glyphed, actionable. Progress and success chatter print as appropriate.
Quiet	`-q`, `--quiet`	Suppresses progress and success chatter. Errors still print (the What line plus the first remediation command, to stderr). The exit code is unchanged.
JSON	`--json`	A single structured object to stdout, conforming to the error / result shape. Success uses a top-level `result`; failure uses `error`. No color, no glyphs, no prose outside the shape.

--json and --quiet are mutually exclusive

Supplying both is a CLI usage error (TVO-CLI-017, exit 2). --quiet never suppresses errors — it suppresses only success and progress output.

Emoji, celebration, warmth lines, and decorative glyphs appear only in interactive human (TTY) output. --json and --quiet carry none of it — this preserves the machine contract.

The four global flags¶

These four are declared once and accepted by every command:

Flag	Meaning
`--json`	Emit the machine-readable structured object — the agent/CI contract.
`-q`, `--quiet`	Suppress success and progress output. Errors are still shown.
`--justification <text>`	A human or compliance reason, recorded in the signed audit entries the command writes. A repository policy (`tovio policy audit`) may require one before selected security-sensitive mutations.
`--no-sync`	Skip the opportunistic auto-sync for this one command. `TOVIO_NO_SYNC` suppresses it persistently.

-h / --help is also available on every command and subcommand, and prints the same text as tovio help <command>.

There is no -C, --repo, --no-color or --yes

TOVIO has no directory-override flag: run the command from inside the repository, or from a subdirectory of it. Color is controlled by the NO_COLOR environment variable rather than a flag. Confirmation is per-command and explicit — tovio obliterate takes a verbatim --confirm phrase, and no command accepts a blanket --yes.

Auto-sync is on by default¶

sync.auto defaults to on, so a command that mutates the repository may opportunistically sync it. Turn that off for one command with --no-sync, for the shell with TOVIO_NO_SYNC, or persistently with tovio config set sync.auto off.

`--format`¶

--format is not a global flag — it is declared per command, and it means different things on different ones.

Commands	Values
`log`, `change list`, `audit log`	`human` (default), `json`, `csv`, `template:<spec>`
`explain <lens>`, and `--explain` on `land` / `health`	`human` (default), `json`, `html`
`audit graph`	`json` (default), `dot`, `mermaid`

A global --json always overrides --format; --format json and --json produce the same document where both apply. tovio diff has no --format — it takes no flags of its own at all.

Color and `NO_COLOR`¶

Color is used to classify, never to decorate. Disable it by setting the NO_COLOR environment variable; there is no --no-color flag. Color also switches itself off outside human mode, and whenever the target stream is not a terminal. Setting TOVIO_ASCII additionally degrades the glyph set to ASCII (✓ becomes [ok], 🔒 becomes (locked)). Meaning is always carried by the words and the exit code, not the decoration.

$ NO_COLOR=1 tovio status

Aliases¶

TOVIO ships far fewer aliases than the short forms Git users expect — there is no st, s, u, cl, cx, sw, d or lg. The aliases that do exist are these:

Alias	Canonical
`tovio br`	`tovio branch`, itself the git-compat alias for `tovio lane`
`tovio rename`	`tovio mv`
`tovio remote rm`	`tovio remote remove`
`tovio unlock <path>`	`tovio lock release <path>` (deprecated)
`tovio locks`	`tovio lock list` (deprecated)

An alias is a rename, never a behavior change — it resolves to the canonical command with the same flags, output, and exit codes. The two deprecated lock aliases additionally print a one-line stderr note.

Git-compat aliases¶

Every TOVIO adopter is a Git migrant, so TOVIO ships a git-compat layer for the Git commands whose muscle memory is strongest. Each does the right TOVIO thing (or explains what to do instead) and prints a single gentle one-line note to stderr naming the native equivalent — training wheels that teach, never silent redirection. The note never pollutes --json stdout or piped output.

Git command	TOVIO action	Gentle note
`tovio add [<path>…]`	no-op (the working copy is always tracked)	TOVIO tracks changes automatically — there is no staging area. See `tovio status`.
`tovio branch [<name>] [-d]`	`tovio lane` with the same arguments	TOVIO calls these `lane`s
`tovio checkout [-b] <name>`	`tovio switch <name>`; `-b` creates the lane first	`"tovio switch"` moves between branches
`tovio stash`	explains that your work is already a tracked change	your work is already a tracked change — see `tovio status`
`tovio reset`	points at `tovio undo`	`"tovio undo"` reverses operations; file-level restore arrives later
`tovio push` / `tovio pull` with no arguments	prints the explicit form instead of transferring	TOVIO unifies git push/pull as `tovio sync`

push and pull are not aliases — they are the real one-direction relay primitives, and with arguments they transfer. Only the bare, argument-less invocation prints the migrant hint.

A user who has internalized the native command can silence the layer:

tovio config set compat.git.notes off      # stop showing the gentle notes

The same is available for one shell with TOVIO_GIT_COMPAT_NOTES=off. There is no setting that disables the git-compat commands themselves.