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 identifyvolli helpPress ⌘, 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.
Addressing
Section titled “Addressing”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:
- An explicit
--project <name>. VOLLI_SESSIONandVOLLI_TICKET, which Volli sets in every session it starts. This is how an agent can runvolli session donewith no arguments.- 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.
Preview writes
Section titled “Preview writes”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.
Environment
Section titled “Environment”| 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.
Exit codes
Section titled “Exit codes”| 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 |
Command index
Section titled “Command index”These links retain the anchors used by earlier documentation.
Human-visible effects and non-effects
Section titled “Human-visible effects and non-effects”See command effects for the durable writes, visible outcomes, and non-effects of each command.
Error codes and recovery
Section titled “Error codes and recovery”See CLI errors for refusal codes and safe next actions.