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 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.

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 to doing is what creates the worktree and starts the agent.

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 sessions, with the short handles session peek takes.

volli session peek

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

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

volli session done

volli session done [--reason <text>]

Signals that the session’s work is finished and moves the ticket to Needs Review. 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. The --reason text appears on the board.

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 help

volli help [<command> | <topic>]

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

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 all three in the sessions it starts.

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`, `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