Skip to content

CLI setup and context

volli reads and updates the local plan through the running app. Terminal companions opened by Volli already have it on PATH.

Check the connection and context from a terminal companion:

volli identify
volli help

Press ⌘, to open Settings in its own window, then choose About to check or repair the installation under Diagnostics. A terminal outside Volli can read the plan, but naming a Session in it does not authenticate the terminal for writes. Write access comes from the environment Volli supplies.

Every public command accepts --json. Full command syntax is in CLI commands; recovery codes are in CLI errors. Value options also accept --opt=value; the value after the first = is taken verbatim, even if it starts with --. Column options ignore case and accept "Needs Review" or needs_review.

session list defaults to active Sessions plus activity in the last 24 hours, including in JSON. Use --all, --since <when>, or --state <s>[,<s>...] to adjust the fleet view. JSON adds hidden beside sessions. session show reads metadata and ancestry; list and peek name pending delegated subagents.

ticket list --json --no-body omits ticket bodies when you only need a summary. Without --no-body, JSON keeps the bodies; the text table never includes them. Older app builds may ignore --no-body, so use --status, --project, and --limit to narrow large results.

ticket show prints comment bodies in full. Other log prose remains capped; ticket show --full and ticket events --full lift those caps without changing the untrusted-prose framing. JSON is always uncapped.

Ticket commands that take an <id> want a display ID, like VLT-12. Session commands use the short handles printed by volli session list.

Where an ID is optional, volli resolves it in a fixed order and stops at the first answer:

  1. An explicit --project <name>.
  2. VOLLI_SESSION and VOLLI_TICKET, which Volli sets in every session it starts. This is how an agent can run volli session done with no arguments.
  3. The current directory, if it belongs to a registered project or a ticket worktree.

volli never guesses past that. If more than one project or ticket fits, the command fails with AMBIGUOUS_PROJECT or AMBIGUOUS_TICKET instead of picking one.

A write whose command help lists --dry-run can resolve and validate its target without changing it. Plain output describes the durable writes, visible effects, and non-effects the real command would have. --json returns the same versioned plan that a registry-projected tool returns through its dryRun argument.

A preview creates no durable ID, row, event, Session, model turn, notification, process, worktree, or file write. It still performs the reads the real call would, including --body-file, --append-file, and --file, so it validates the same input. A later real call validates again and can lose a race.

A verb whose help does not list --dry-run refuses a preview instead of ignoring it, so a preview request never falls through to the real write.

Variable Purpose
VOLLI_SOCKET Path to the app’s Unix socket. Required by every command except identify, help, and app launch.
VOLLI_SESSION The current session. Set by Volli; session done and session blocked act on it.
VOLLI_TICKET The current ticket, used when you omit <id>.

Volli sets VOLLI_SESSION and VOLLI_TICKET in every session it starts, terminal and chat alike. It exports VOLLI_SOCKET into terminal sessions and bakes it into the bundled volli shim, so the CLI reaches the app either way.

Code Meaning
0 Success
1 The command ran and failed
2 Usage error (bad flag or missing argument)
3 The app couldn’t be reached. Retryable

These links retain the anchors used by earlier documentation.

Command
volli identify
volli board
volli project list
volli label list
volli label merge
volli model list
volli cost
volli ticket list
volli ticket show
volli ticket events
volli ticket brief
volli ticket create
volli ticket update
volli ticket move
volli ticket comment
volli ticket signal
volli worktree status
volli worktree diff
volli worktree sync
volli conflicts
volli session list
volli session show
volli session answer
volli session peek
volli session done
volli session blocked
volli session link
volli notify
volli app launch
volli prompt baseline
volli doctor
volli perf top
volli perf stalls
volli perf compare
volli help
volli hook

See command effects for the durable writes, visible outcomes, and non-effects of each command.

See CLI errors for refusal codes and safe next actions.