Skip to content

Shell completions & prompt

Two small things make TOVIO feel native in a terminal: tab-completion that knows the commands, flags, lanes, and changes you are reaching for, and a prompt segment that shows your change ID, sync status, and conflict count without your having to ask. This page sets up both.

Shell integrations are implemented

tovio completions and the prompt provider described below are available in the current CLI.

Completions

TOVIO generates completion scripts for zsh, bash, and fish (and, with the same command, PowerShell and elvish: tovio completions powershell). Generate the script for your shell and load it from your shell's startup file.

Write the completion into a directory on your fpath --- for example a personal ~/.zsh/completions:

mkdir -p ~/.zsh/completions
tovio completions zsh > ~/.zsh/completions/_tovio

Make sure that directory is on your fpath and completion is initialized, in ~/.zshrc:

fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

Open a new shell, type tovio and press ++tab++.

Load the completion from your ~/.bashrc:

tovio completions bash > ~/.tovio-completion.bash
echo 'source ~/.tovio-completion.bash' >> ~/.bashrc

Completions for tovio need the bash-completion package installed. Open a new shell to pick up the change.

Drop the completion into fish's completions directory --- it is loaded automatically:

tovio completions fish > ~/.config/fish/completions/tovio.fish

No further setup; new shells have it.

Once it is loaded, completion covers the everyday command set, their flags, and live values where it makes sense --- lane names for tovio switch, change IDs for commands that take one --- so you type less and misremember less.

The git-compat aliases complete too

If muscle memory still types push or checkout, the git-compat aliases complete alongside the native commands. Completion teaches the native equivalent gently; it never scolds you for reaching for the Git word.

Prompt segment

tovio status --prompt prints a compact, already-formatted one-line segment for your shell prompt, and exits non-zero outside a TOVIO repository (so a when/guard hides it where it is irrelevant). It reads local state only --- no network --- and keeps these facts in view right where you look:

  • Lane + change ID --- your current lane and the short ID of the change you are working on.
  • Working changes (✚N) --- uncommitted changed files, if any.
  • Sync status (⇣N) --- how many commits your lane is behind main, shown only on a feature lane. It is a network-free count, so it is always instant. (How far ahead you are is a documented follow-on --- run tovio health for the full landability picture.)
  • Conflict count (✖N) --- how many conflict objects are stored.
  • Isolated paths (🔒N) and a token warning (⏳) when an agent capability token is expiring or already expired.

Because conflicts are first-class data in TOVIO rather than a blocked state, a non-zero conflict count in your prompt is information, not an alarm --- your work keeps moving, and you resolve when you are ready. Prefer machine-readable fields? tovio status --prompt --json emits {branch, change, changed, conflicts, isolated, behind, token_warning}.

Starship

Add a custom segment to ~/.config/starship.toml:

[custom.tovio]
command = "tovio status --prompt"
when = "tovio status --prompt"
format = "[$output]($style) "
style = "bold purple"

command prints the compact segment; when succeeds (exit 0) only inside a TOVIO repository, so the segment appears only where it is relevant.

Powerlevel10k

Register a custom segment in ~/.p10k.zsh and add it to your prompt elements:

function prompt_tovio() {
  local seg
  seg="$(tovio status --prompt 2>/dev/null)" || return   # non-zero outside a TOVIO repo
  p10k segment -f magenta -t "$seg"
}

Add tovio to your POWERLEVEL9K_LEFT_PROMPT_ELEMENTS (or the right-prompt list) next to your existing VCS segment, and reload your shell.

The prompt reports; it never blocks

tovio status --prompt only reads state --- it never mutates your repository, and it reads local state only (no network), so it never stalls a command. Outside a TOVIO repository it prints nothing and exits non-zero, so your prompt steps aside.

Where to go next

  • New to the commands these complete? Start with get started.
  • Want the same facts inside your editor instead? See editor integrations.
  • Building tooling rather than typing commands? The Node SDK exposes the same state programmatically.

Last reviewed September 9, 2026

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