Skip to content

Read your status

tovio status is the source of truth. Any time you're unsure what change you're on, what's modified, whether anything conflicts, or whether an agent token is about to expire — this one command answers, completely. You never have to reconstruct state from memory or chain several commands together.

See the current state

$ tovio status

In a simple solo repository — no policies, no agents — the output collapses to the essentials:

  on feature/cgm-sync · chg:a3f7b2…
  modified (2 file(s))
    ~ src/integrations/cgm/dexcom.ts
    + tests/integrations/cgm.test.ts

Read it top to bottom:

  • on <lane> · <change> — the lane you're on and the change you're working in, with its stable Change ID (chg:…). The change is your unit of work; in TOVIO a lane is a landing target, not a workspace. Before your first commit an extra line says (no commits yet).
  • relay — relay origin · ahead 3, behind 0 names your relay and how far ahead/behind it you are. It appears only while a fresh frontier from a successful authenticated sync exists (15 minutes); before that, or once it has expired, the line is simply omitted.
  • modified (N file(s)) — every tracked file you've touched. ~ means changed, + added, - removed, and R old → new a recorded rename. There is no staging step: everything listed here is already part of the current change. With nothing touched the line reads clean — nothing to commit.

What status shows in a team repository

Once a repository has policies, agents, or open conflicts, status grows extra sections — and only those that apply. Each line is aligned and glyph-tagged so you can scan it:

  on feature/cgm-sync · chg:a3f7b2…
  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_9f3c…  cursor  model anthropic:claude-opus-4-8 · branches agent/cursor/** · expires in ~5h
  ⏳ agent token `cap_9f3c…` expires in ~5h — renew with `tovio agent renew cap_9f3c…`
  • 🔒 protected marks a modified path that a policy governs. Status never prints the policy's contents; the effective policy for a path is tovio policy show <path>, and whether an identity satisfies it is tovio policy test. Managing those policies lives in the permissions guides.
  • Unresolved conflicts list each conflicted path with its kind (content, delete/modify, rename/rename, …) and the command to resolve it. A conflict here does not block you — see Resolve conflicts. tovio status --conflicts additionally reports whether the lane would land cleanly onto main (landing into main: clean ✓ (fast-forward) or the conflicts it would store).
  • Isolated paths — files pinned at their last-known-clean version while a teammate's upstream conflict is still open — and active locks each get a section when present.
  • Active agent sessions list each live capability token, its agent, model, lane scope, and expiry; an expiring or expired token gets its own ⏳ / ✗ line with the tovio agent renew command.

Agent sessions are team-tier; the key-expiry banner is designed, not shipped

The protection and agent-session sections only appear once you've created a policy or issued an agent token. A solo repo never shows them. The agent surface (tovio agent, capability tokens, provenance) is implemented in the current source tree; no generally available package has been published. See Agents. The CLI specification also designs a proactive banner when your own access certificate is about to expire; today's status does not print one — check key health with tovio key status.

Scripting against status (--json)

Every command — including status — supports --json for scripts and agents. The JSON form carries the structured state and none of the glyphs, color, or warmth lines from the human output:

$ tovio status --json

{
  "result": {
    "agent_sessions": [],
    "branch": "feature/cgm-sync",
    "change": "chg:a3f7b2…",
    "changes": [
      "~ src/integrations/cgm/dexcom.ts",
      "+ tests/integrations/cgm.test.ts"
    ],
    "clean": false,
    "conflicts": [
      { "path": "src/shared/types.ts", "kind": "content", "status": "unresolved" }
    ],
    "expired_tokens": [],
    "expiring_tokens": [],
    "isolated": [],
    "locks": [],
    "protected": [],
    "unborn": false
  }
}

The lane is reported under the branch key (the machine contract predates the lane rename). A relay object (name, ahead, behind) is added only while a fresh sync frontier exists, and --conflicts adds a landing object.

Two more shapes are built for automation:

  • tovio status -q prints nothing at all — the exit code is the answer.
  • tovio status --prompt prints a compact one-line segment for a shell prompt (Starship, p10k): <lane> <short-change> [✚changed] [⇣behind] [✖conflicts] [🔒isolated] [⏳]; with --json it emits the same counts as fields.

Short alias

The CLI specification reserves tovio st as the short alias for tovio status; it is not in the shipped binary yet, so use the full name.

Where to go next

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure