Command effects
Check what a command changes before you run it. The entries come from the same Verb Registry that command help and write previews use. They cover shell commands and named agent tools, so an entry here does not mean you can run it at a terminal.
Preview a write
Section titled “Preview a write”Run volli help <command> to check whether a shell command supports --dry-run.
A preview validates the request without applying the write, but it still reads
the files you pass with flags such as --body-file.
Preview a ticket move:
volli ticket move VLT-12 --to needs-review --dry-runReplace VLT-12 with your ticket’s display ID. The real command validates
again: a preview reserves nothing and does not guarantee the write will succeed.
Effects by command
Section titled “Effects by command”ticket.create
Preview: supports --dry-run.
- Durable writes
- Create one Ticket and its attributed Ticket creation event.
- What a person sees
- The new Ticket appears on the board in the selected column.
- Does not do
- Creating in Doing does not start a Session or submit a kickoff turn.
- Worktree intent is recorded, but this command does not materialize a checkout.
ticket.update
Preview: supports --dry-run.
- Durable writes
- Update the requested Ticket fields and append attributed Ticket events for changes.
- What a person sees
- Updated fields appear on the Ticket card and in its Ticket view.
- Does not do
- The Ticket does not move, no Session starts, and no worktree is materialized.
ticket.move
Preview: supports --dry-run.
- Durable writes
- Update the Ticket's board status and order and append one status-change Ticket event.
- What a person sees
- The Ticket moves to the selected board column.
- If Automatic triggers is on and the destination column has an armed Automation, a cancellable arrival can start a fresh Run.
- Moving from Doing or Needs Review to Backlog, Todo, or Done interrupts the Ticket's live Sessions.
- Does not do
- Without an enabled, armed Automation, the move does not start a Session, submit a kickoff turn, or create a worktree.
ticket.comment
Preview: supports --dry-run.
- Durable writes
- Create one attributed Ticket comment and its Ticket activity event.
- What a person sees
- The comment appears in the Ticket activity feed.
- Does not do
- The Ticket does not move and no Session starts.
ticket.signal
Preview: supports --dry-run.
- Durable writes
- Create one attributed Ticket signal and its signaled Ticket event, in one transaction.
- What a person sees
- The verdict appears in the Ticket activity feed and in ticket show's latest-signal lines.
- Does not do
- The Ticket does not move: signals are orthogonal to the board by design.
- No Session starts, no notification fires, and no earlier signal is edited or erased.
ticket.archive
- Durable writes
- Mark the Ticket archived and append its attributed archive event.
- What a person sees
- The Ticket leaves the active board and remains available as archived history.
- Does not do
- The Ticket worktree is preserved and active Sessions are not ended.
worktree.sync
Preview: supports --dry-run.
- Durable writes
- Merge the base ref into the ticket worktree's checked-out branch, leaving a merge commit or an unresolved merge in that worktree.
- What a person sees
- The ticket's worktree status and Change Set show the merged base, or the conflicted merge awaiting resolution.
- Does not do
- No Ticket moves, no Session starts, and no signal is recorded.
- Nothing is fetched, pushed, or pulled: no remote is contacted and no credential is used.
- No gate, check, or CI run is started or waited on.
label.merge
- Durable writes
- Move every association from the merged-away label onto the surviving one, and record a labels_changed event per affected Ticket.
- Retire the merged-away Label as an alias, so its old name keeps resolving to the survivor.
- What a person sees
- Affected Ticket cards show the surviving label, and the merged-away one leaves the board's Label filter.
- Does not do
- No Ticket moves, no Ticket loses a Label it was wearing, and the retired name is not re-created later.
session.start
- Durable writes
- Create one durable Ticket Session, freeze its start inputs, and submit its kickoff turn after a ready attachment.
- What a person sees
- The app raises an actionable in-app toast with Open session for an agent-originated start.
- Does not do
- The Ticket does not move.
- The app does not steal focus or navigate until the person uses Open session.
- The calling Session is not paused: it is told about the started Session through later notices, not by waiting.
session.done
Preview: supports --dry-run.
- Durable writes
- Append a completed done signal command and receipt to the current Session ledger.
- Create one attributed Ticket comment holding this Session's final todo list, when it kept one and belongs to a Ticket.
- What a person sees
- The done signal and optional reason appear in the Session's durable history.
- The Session's final todo list appears in the Ticket activity feed.
- Does not do
- No Ticket moves, the Session identity remains openable, and its worktree is not removed.
- No comment is written for a Board Session or for one that kept no todo list.
session.blocked
Preview: supports --dry-run.
- Durable writes
- Append a completed blocked signal command and receipt to the current Session ledger.
- Create one attributed Ticket comment holding this Session's unfinished todo list, when it kept one and belongs to a Ticket.
- What a person sees
- The Session raises attention in the app and shows the optional reason.
- The Session's todo list as it stood appears in the Ticket activity feed.
- Does not do
- No Ticket moves, and the Session is not archived or deleted.
- No comment is written for a Board Session or for one that kept no todo list.
session.link
Preview: supports --dry-run.
- Durable writes
- Record the harness-native resume identity on the current terminal attachment.
- What a person sees
- Reopening or resuming the Session uses the recorded harness conversation.
- Does not do
- No model turn starts, no Ticket moves, and no new Session is created.
notify
Preview: supports --dry-run.
- Durable writes
- None.
- What a person sees
- Electron raises a native macOS notification with the supplied title and body.
- Does not do
- It is not an in-app Sonner toast and creates no Ticket row, Ticket event, or Session event.
doctor
Applies when --fix is supplied.
Preview: supports --dry-run.
- Durable writes
- Regenerate Volli-managed CLI links, wrappers, harness configuration, and shell integration, then refresh Session PATH adoption for future Sessions.
- What a person sees
- The CLI prints the repair result and a fresh integration check.
- Does not do
- The running Session keeps its startup environment; no Ticket, Session, model turn, or notification is created.
app.launch
- Durable writes
- None.
- What a person sees
- The Volli desktop app opens or remains running.
- Does not do
- No Ticket or Session is created, moved, or signalled.
automation.run
- Durable writes
- Create one Automation Run with its resolved model and reasoning, open the fresh Session it names with the `automation` Actor, and deliver the Automation's Instructions as that Session's first message.
- What a person sees
- The Run appears in the Ticket's Run history and its Session is marked with the `automation` Actor — the same record a person's Run by hand writes, with nothing naming the agent that asked for it.
- Does not do
- The Ticket does not move, and no existing Session is woken: a Run always opens a fresh one.
- It does not wait for the Run to finish; the calling Session watches the Run's Session and hears about it through later notices.
- No Automation is created, edited or armed — this verb runs a saved one and authors nothing.
session.stop
- Durable writes
- Append a session.stop command and its stopped event, naming the calling Session as the actor, to the target Session's ledger.
- What a person sees
- The target Session shows Stopped wherever sessions list, with the stop and its actor in its durable history.
- Does not do
- The Session is not archived or deleted, its worktree is untouched, and no Ticket moves.
- No new Session starts, and the stopped Session can be reattached by a person.
session.send
- Durable writes
- Append a message.submit command carrying the marked steering message to the target Session's ledger.
- What a person sees
- The steering message appears in the target Session's transcript, marked with the sending Session.
- Does not do
- It does not wait for the target's turn to finish; an active delegate reports through its delegation answer, and other targets through a later watch notice.
- No Ticket moves, no Session stops, and no new Session starts.
session.delegate
- Durable writes
- Create one durable Subagent Session with this Session as its parent, freeze its start inputs, and submit the task as its kickoff turn after a ready attachment.
- When the subagent's first turn completes, append a notice from Volli to this Session's ledger naming the subagent and its state and quoting its final message as the subagent's prose; a long message is cut, with `session answer` naming the rest.
- What a person sees
- The subagent appears in the parent Session's Activity Island, where the person can inspect its transcript or open it as a tab. It has no separate Session-list row.
- Does not do
- No Ticket moves, and the person driving is not asked anything.
- This Session is not paused: the call returns at once and the answer arrives later.
mcp.list
- Durable writes
- None.
- What a person sees
- Nothing changes: this reads the same configuration Settings → Configure → MCP Servers shows.
- Does not do
- No server is connected, no process is started, and no Session's tool list changes.
mcp.preview
- Durable writes
- None.
- What a person sees
- A local server's process is started for the length of the handshake, and a remote server sees one connection.
- Does not do
- Nothing is saved: the project's MCP configuration is exactly as it was, and no Session gains a tool.
mcp.install
- Durable writes
- Store the server's transport, its discovered tool catalog, the tools selected from it, and the provenance supplied with the request, keyed on the server id so a repeat updates rather than duplicates.
- Append one durable audit record naming the request, its source, its outcome, and what to do if it failed.
- What a person sees
- The server appears in Settings → Configure → MCP Servers with its provenance and selected tools, and the install shows in that project's MCP history.
- Does not do
- The calling Session gains nothing: its tool list was frozen at birth and is byte-identical afterwards. The selected tools reach the next Session created.
- No package is downloaded, unpacked or verified, and no existing Session's tool list changes.
mcp.refresh
- Durable writes
- Replace the stored tool catalog with the one just discovered, or mark the server stale with the failure while keeping the last working catalog.
- What a person sees
- The server's tool list and status update in Settings → Configure → MCP Servers.
- Does not do
- No existing Session changes: a Session's MCP tools are frozen at birth, and a refreshed catalog reaches the next Session created.
mcp.enable
- Durable writes
- Set the server's enabled flag.
- What a person sees
- The server's On checkbox in Settings → Configure → MCP Servers.
- Does not do
- No existing Session gains a tool: a frozen tool list never changes. The next Session created sees the change.
mcp.disable
- Durable writes
- Clear the server's enabled flag.
- What a person sees
- The server's On checkbox in Settings → Configure → MCP Servers.
- Does not do
- No existing Session loses a tool: a frozen tool list never changes, and the server's configuration is kept so reattachment keeps working.
mcp.tools
- Durable writes
- Replace which of the stored catalog's tools are marked on.
- What a person sees
- The per-tool checkboxes in Settings → Configure → MCP Servers.
- Does not do
- No existing Session changes: its MCP tools are frozen at birth. The selection reaches the next Session created.
mcp.remove
- Durable writes
- Delete the server row, its stored catalog, and its tool selection.
- Append one durable audit record naming what was removed, by which Session, and what it may have broken.
- What a person sees
- The server leaves Settings → Configure → MCP Servers, and the removal shows in that project's MCP history.
- Does not do
- The calling Session's frozen tool list does not change, and no Session currently attached loses a tool mid-run.
- Session history is not edited: transcripts still name the tools that were called.
See CLI commands for syntax and CLI errors for recovery.