CLI commands
This reference lists shell commands. Run volli help <command> for the full
option table, allowed values, and an example from your installed build.
All public commands accept --json. Writes that support --dry-run list it in
command help. See CLI setup and context for addressing and
previews, command effects for what a write
changes, and CLI errors for recovery.
Orientation
Section titled “Orientation”volli identify
Section titled “volli identify”volli identify [--project <name>]Prints the resolved project, ticket, Session, and tool environment. Run it first when a command targets the wrong context, or when a tool cannot be found.
volli board
Section titled “volli board”volli board [--project <name>]The whole board, grouped by column.
volli project list
Section titled “volli project list”volli project listEvery registered project, with its path and ticket prefix.
volli label list
Section titled “volli label list”volli label list [--project <name>]A project’s labels. Agents use it to check that a label exists before applying it.
volli label merge
Section titled “volli label merge”volli label merge --from <name> --into <name> [--apply] [--project <name>]Folds one label into another. Without --apply it previews the affected
tickets. With --apply, every association moves onto the surviving label, and
the merged-away name becomes an alias that still resolves.
volli model list
Section titled “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. A printed provider/model value is
what an Automation’s Runtime or an agent’s session_start tool expects.
volli cost
Section titled “volli cost”volli cost [--ticket <id>] [--session <handle>] [--project <name>] [--all-projects] [--since <when>] [--group-by ticket|session|model|day|cause]What Sessions consumed: tokens, cost, and cache class. This is Volli’s own
measurement of its Sessions, not a provider account balance or an invoice. ~
marks a catalogue estimate, + a total that is only partly priced, and — a
total that nothing could be priced for. --group-by cause separates chat
replies, compaction, utility work such as chat names, and decision-model calls.
Tickets
Section titled “Tickets”volli ticket list
Section titled “volli ticket list”volli ticket list [--status <column>] [--priority low|medium|high] [--label <name>] [--project <name>] [--limit <n>] [--no-body]A project’s tickets. Filters combine, so --status doing --priority high
returns only tickets matching both.
For a compact JSON result, use --json --no-body. Every field except the body
stays. Use ticket show VLT-12 to read one ticket’s body. JSON includes bodies
without the flag; the text table omits them either way. Older app builds may
ignore --no-body, so use filters and --limit for large boards.
volli ticket show
Section titled “volli ticket show”volli ticket show <id> [--events <n>] [--comments <n>] [--comments-only] [--full]The full ticket, optionally with recent history and comments. Comment bodies
print in full. Other log prose is capped at 1,000 characters; --full or --json
returns the rest. Prose stays quoted as untrusted data.
volli ticket events
Section titled “volli ticket events”volli ticket events <id> [--limit <n>] [--full]The append-only history of a ticket. --full lifts text caps; --json is always
uncapped. session_started and session_resumed print the Session’s short
handle inline, and by= names who asked: a person, an Automation with its run
id, a Session, or Volli itself. A resume with no recorded origin is
by=unknown.
volli ticket brief
Section titled “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 you start an agent, to see what it will read.
volli ticket create
Section titled “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] [--dry-run]--title is required. --body and --body-file are mutually exclusive, so
pass one of them. Repeat --label to apply 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
Section titled “volli ticket update”volli ticket update <id> [--title <text>] [--body <text> | --body-file <path> | --append <text> | --append-file <path> | --edit <old> <new>] [--priority low|medium|high] [--add-label <name>]... [--remove-label <name>]... [--harness <harness>] [--base <branch>] [--dry-run]Pass exactly one body mutation. --append adds to the end; --append-file reads
that text locally from a file. --edit replaces the first occurrence of <old>
with <new>. Value options accept --opt=value, including values starting with
--: use --append="--- x" for a Markdown separator.
volli ticket move
Section titled “volli ticket move”volli ticket move <id> --to <column> [--dry-run]Columns are backlog, todo, doing, needs-review (or review), and done.
Case is ignored, and board labels such as "Needs Review" and needs_review
work here and in ticket list --status and ticket create --status. Moving a
ticket updates the board and picks no model by itself. The move counts as a
Deliberate move, so it starts a Session only when the destination column
has an armed, enabled Automation.
volli ticket comment
Section titled “volli ticket comment”volli ticket comment <id> (-m <text> | --file <path>) [--dry-run]Adds a comment to the ticket’s activity feed, attributed to the Session it ran in.
volli ticket signal
Section titled “volli ticket signal”volli ticket signal <id> --kind <kind> --verdict <verdict> [--detail <text>] [--dry-run]Records a typed verdict on a ticket: which stage, and how it went. --kind is
validate, implement, review, merge, human-gate, or budget.
--verdict is pass, fail, or blocked. --detail carries one line of
prose for a person, while the verdict is what machines read.
Signals are append-only. The latest signal of each kind supplies its current verdict. No signal moves the ticket.
Worktrees
Section titled “Worktrees”volli worktree status
Section titled “volli worktree status”volli worktree status [<id>]The ticket’s branch, its base, and how far the two have diverged.
volli worktree diff
Section titled “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.
Neither command writes anything.
volli worktree sync
Section titled “volli worktree sync”volli worktree sync [<id>] [--abort] [--dry-run]Merges the ticket’s base branch into its worktree branch and reports what happened. This is the one worktree command that writes, and it needs an authenticated Session.
It merges origin/<base> if a fetch has already created that ref, or the local
base branch otherwise. It contacts no remote, uses no credential, and returns
without waiting for checks or CI.
A conflict is an outcome, not an error. The reported status is conflicted,
every conflicted path is listed, and the worktree is left conflicted for you to
resolve and commit. Branch on status, not on the exit code. --abort undoes a
merge left in flight; nothing else cleans up after one.
volli conflicts
Section titled “volli conflicts”volli conflicts [--project <name>]Lists active ticket worktrees that change the same paths, ordered by how much they overlap. Use it to find concurrent edits before you merge. It reports shared paths, not predicted merge failures: two tickets that edit different parts of one file may still merge cleanly. This command is read-only.
Sessions
Section titled “Sessions”volli session list
Section titled “volli session list”volli session list [--project <name>] [--ticket <id>] [--all] [--state <s>[,<s>...]] [--since <when>]Active and recent terminal and chat Sessions, each with its title and short
handle. By default: working, waiting, interrupted, terminal running,
or an idle Session with pending subagents at any age, plus activity in the last 24 hours. --since replaces that activity
window with a look-back (7d, 24h, 90m) or RFC 3339 instant. --all removes
the window. --state intersects those filters using the exact printed words:
working, waiting, idle, stopped, interrupted, running, exited.
Project and ticket filters still apply.
Rows sort by most recent activity. Text ends with an older-row count when the
activity window omitted rows; JSON keeps sessions and adds hidden for that
count, after the explicit project, ticket and state filters. This default filter also
applies to --json. Pending delegated subagents appear on chat rows and in
session peek, even when a child is filtered out. Terminal and chat rows say who
started them unless a person did, and who last reattached them. Reattachment is
visible before any new message or turn.
volli session show
Section titled “volli session show”volli session show <handle>Session metadata without a transcript: title, role, ticket, project, state,
who started it (a person, an Automation with its run id, or a parent Session),
who last reattached it and its last few successful reattachments. Chat details
also name the latest turn’s sender, parent and children with states, pending
subagents, model and reasoning/tier. Both include usage/cost and creation/last-activity
ages. The reattacher and the next message’s sender are separate facts. session show, peek, and answer take the same
short handles.
volli session answer
Section titled “volli session answer”volli session answer <handle>Prints a chat Session’s final message in full. A delegating agent can use it to read a subagent’s answer. It reports the state of the latest turn (completed, running, interrupted, stopped, failed, not-started) and then the last assistant message, untruncated and quoted as another Session’s prose.
volli session peek
Section titled “volli session peek”volli session peek <handle> [--lines <n>]Shows what a Session is doing, from its short handle, so one agent can see another’s work without attaching to it.
A terminal returns its recent output. A chat returns its activity state, who started it and, after a stop, who resumed it, then a compact transcript tail, with one line per message and truncated tool calls and text.
--lines sets 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
Section titled “volli session done”volli session done [--reason <text>] [--dry-run]Records that the Session’s work is finished. It acts on the Session named by
VOLLI_SESSION without moving the ticket. Run ticket move separately when the
ticket’s status needs to change.
If the Session kept a todo list and belongs to a ticket, its last version is posted to that ticket as a comment. A Board Session has no ticket to post to, and a Session that never used the todo tool leaves no comment.
volli session blocked
Section titled “volli session blocked”volli session blocked [--reason <text>] [--dry-run]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.
If the Session kept a todo list and belongs to a ticket, its current list is also posted as a ticket comment.
volli session link
Section titled “volli session link”volli session link <harness-session-id> [--dry-run]Records the harness’s own session ID so Volli can resume that conversation later.
volli notify
Section titled “volli notify”volli notify -m <text> [--title <text>] [--dry-run]Sends a native macOS notification.
volli app launch
Section titled “volli app launch”volli app launch [--timeout <n>]Starts Volli if it isn’t already running.
volli prompt baseline
Section titled “volli prompt baseline”volli prompt baseline [--ticket <id>] [--project <name>]Estimates the prompt baseline for a fresh Board 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
Section titled “volli doctor”volli doctor [--fix] [--dry-run]Checks the live CLI, wrapper, harness, and shell integration. --fix
regenerates the parts Volli owns and checks again. --dry-run only works with
--fix; it previews the repair without changing anything.
Performance diagnostics
Section titled “Performance diagnostics”These read-only commands inspect stalls recorded on this Mac. The default
window is 24 hours. --since accepts a look-back such as 7d, 24h, or 90m,
or an RFC 3339 instant.
volli perf top
Section titled “volli perf top”volli perf top [--since <when>] [--by operation|door|label|version|session] [--process main|renderer] [--limit <n>]Ranks groups by total stalled milliseconds. --by defaults to operation;
--limit defaults to 10 and accepts at most 100. Output includes percentiles
and rates per hour the app was observed running.
volli perf stalls
Section titled “volli perf stalls”volli perf stalls [--since <when>] [--process main|renderer] [--door <door>] [--operation <op>] [--label <label>] [--version <build>] [--limit <n>]Lists individual stalls, newest first, with their duration and any known
operation, interaction label, Session, and build. --limit defaults to 20 and
accepts at most 500. A hint names the last door call before an unattributed
main-process stall; it is a lead to investigate, not a proven cause.
volli perf compare
Section titled “volli perf compare”volli perf compare --version <a> --version <b> [--since <when>] [--by operation|door|label|version|session] [--process main|renderer] [--limit <n>]Pass --version exactly twice. Each value can match a version, a build label,
or the version-plus-build printed by perf top --by version. A negative delta
means build B stalled less per observed hour. --by defaults to operation;
--limit defaults to 10 and accepts at most 100.
Renderer diagnostics can include Long Animation Frame measurements for script, blocking, rendering, and style/layout work. Missing measurements mean unknown, not zero. These measurements overlap; do not add them together. GPU and compositor work is mostly outside these measurements.
Help and harness hooks
Section titled “Help and harness hooks”volli help
Section titled “volli help”volli help [<command> | <topic>]Topics: concepts, changes, exit-codes, addressing, json, orchestration.
volli hook
Section titled “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 volli help does not list it.
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, so it can never
interrupt a running agent.
<event> is one of session.started, session.ended, turn.started,
turn.completed, input.needed, permission.requested, tool.started,
subagent.completed.