CLI reference

volli is how agents read the plan and report back, and it works just as well typed by hand. It talks to the running app over a local Unix socket.

Every public command accepts --json for machine-readable output.

Addressing

Commands that take an <id> want a display ID, like VC-12.

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

An explicit --project <name>.
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.
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 rather than picking one.

Orientation

volli identify

volli identify [--project <name>]

Prints the project, ticket, and session volli thinks you’re in. Run it first when something isn’t behaving. If this fails, nothing else will work.

volli board

volli board [--project <name>]

The whole board, grouped by column.

volli project list

volli project list

Every registered project, with its path and ticket prefix.

volli label list

volli label list [--project <name>]

A project’s labels. Agents use it to check a label exists before applying it.

volli model list

volli model list [--all]

Lists signed-in providers, model IDs, and reasoning levels. --all also shows signed-out providers and unavailable models. Copy a printed provider/model value into volli session start --model.

Tickets

volli ticket list

volli ticket list [--status <column>] [--priority low|medium|high]
                  [--label <name>] [--project <name>] [--limit <n>]

A project’s tickets. Filters combine, so --status doing --priority high returns only tickets matching both.

volli ticket show

volli ticket show <id> [--events <n>] [--comments <n>]

Full ticket, optionally with recent history and comments.

volli ticket events

volli ticket events <id> [--limit <n>]

The append-only history of a ticket.

volli ticket brief

volli ticket brief <id>

Prints the runtime brief, the exact content an agent receives when it starts on this ticket. Check it before starting an agent to see what it will read.

volli ticket create

volli ticket create --title <text>
                    [--body <text> | --body-file <path>]
                    [--priority low|medium|high] [--status <column>]
                    [--label <name>]... [--project <name>]
                    [--harness <harness>] [--base <branch>] [--no-worktree]

--title is required. --body and --body-file are mutually exclusive. Repeat --label for more than one.

--base sets the branch the ticket’s worktree branches from. --no-worktree skips creating a worktree for the ticket.

volli ticket update

volli ticket update <id> [--title <text>]
                         [--body <text> | --body-file <path>
                          | --append <text> | --edit <old> <new>]
                         [--priority low|medium|high]
                         [--add-label <name>]... [--remove-label <name>]...
                         [--harness <harness>] [--base <branch>]

Pass exactly one body mutation. --append adds to the end; --edit replaces the first occurrence of <old> with <new>.

volli ticket move

volli ticket move <id> --to <column>

Columns are backlog, todo, doing, needs-review, and done. Moving a ticket updates the board; it does not select Model Access or start a structured Session.

volli ticket comment

volli ticket comment <id> (-m <text> | --file <path>)

Adds a comment to the ticket’s activity feed, attributed to the session it ran in.

volli ticket archive

volli ticket archive <id>

Takes the ticket off the board. The worktree and history are kept.

Worktrees

volli worktree status

volli worktree status [<id>]

The ticket’s branch, its base, and how far the two have diverged.

volli worktree diff

volli worktree diff [<id>] [--working-tree]

Defaults to the merge-base range against the ticket’s base branch, the same range a pull request would show. --working-tree shows uncommitted changes instead.

Both commands are read-only.

Sessions

volli session list

volli session list [--project <name>] [--ticket <id>]

Active terminal and chat sessions, each with its title and short handle. session peek takes the short handle.

volli session start

volli session start <id> [-m <text>] [--title <text>] [--model <provider/model>] [--reasoning <level>]

Starts an attended chat on a ticket. The kickoff message supplies a deterministic title when --title is absent; an explicit title is kept unchanged. Model overrides are validated against Model Access before the Session is created.

volli session peek

volli session peek <handle> [--lines <n>]

What a session is doing, by its short handle. Lets one agent see what another is doing without attaching to it.

A terminal answers with its recent output. A chat answers with an activity line — whether it is working, waiting on a person, or idle; how long since anything happened; which turn it is on and how deep into it — followed by a compact transcript tail: one line per message, with the tools it called and its words truncated.

--lines is trailing terminal lines (60 by default) or chat messages (12). Keep it narrow: a peek is spent out of the asking agent’s own context.

volli session done

volli session done [--reason <text>]

Records that the session’s work is finished. The signal lands in the session’s own ledger; the board does not move — an agent may not declare its own ticket ready for review, so the ticket move stays an explicit step. Acts on the session in VOLLI_SESSION.

volli session blocked

volli session blocked [--reason <text>]

Signals that the session has stopped and needs a person. Volli raises attention on that exact session, and the --reason text is what the person sees.

volli session link

volli session link <harness-session-id>

Records the harness’s own session ID so Volli can resume that conversation later.

Other

volli notify

volli notify -m <text> [--title <text>]

Fires a native macOS notification.

volli app launch

volli app launch [--timeout <n>]

Starts Volli if it isn’t already running.

volli prompt baseline

volli prompt baseline [--ticket <id>] [--project <name>]

Estimates the prompt baseline for a fresh Project Session, broken down by section. --ticket measures a Ticket Session and includes that ticket’s Runtime Brief. The estimate excludes tool definitions, the first user message, and provider overhead.

volli doctor

volli doctor [--fix]

Checks the live CLI, wrapper, harness, and shell integration. --fix regenerates the parts Volli owns and checks again.

volli help

volli help [<command> | <topic>]

Topics: exit-codes, addressing, json, orchestration.

volli hook

volli hook <harness> <event> [--socket <path>]

Reports one harness event to Volli. The event payload arrives as JSON on stdin, or as a trailing argument for harnesses that pass it that way.

Volli configures this itself, on the harnesses it launches. You never need to run it, and it is not listed in volli help.

It always exits 0 and prints nothing — outside a Volli session it does no work at all, and inside one a failure to reach the app is silent rather than something that could interrupt a running agent.

<event> is one of session.started, session.ended, turn.started, turn.completed, input.needed, permission.requested, tool.started, subagent.completed.

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. VOLLI_SOCKET is exported into terminal sessions and baked into the bundled volli shim, so the CLI reaches the app either way.

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

Error codes

Every failure prints error[CODE] message and carries one of these codes. The code is stable; the message isn’t, so branch on the code.

Exit	Codes
`2`	`USAGE`, `INVALID_REQUEST`, `UNSUPPORTED_COMMAND`
`3`	`APP_UNREACHABLE`
`1`	`DB_UNAVAILABLE`, `PROJECT_REQUIRED`, `PROJECT_NOT_FOUND`, `AMBIGUOUS_PROJECT`, `TICKET_NOT_FOUND`, `AMBIGUOUS_TICKET`, `SESSION_NOT_FOUND`, `AMBIGUOUS_CONTEXT`, `CONTEXT_REQUIRED`, `CONTEXT_MISMATCH`, `BODY_MATCH_FAILED`, `INVALID_COLUMN`, `INVALID_PRIORITY`, `ARCHIVED_TICKET`, `SESSION_ENDED`, `MODEL_REQUIRED`, `MODEL_UNAVAILABLE`, `PREFIX_CONFLICT`, `FILE_READ_FAILED`, `MUTATION_FAILED`, `SOCKET_PROTOCOL`, `TIMEOUT`

Run volli help exit-codes for the same table, generated from the codes the app actually emits.

All docs as plain text