CLI reference - Voss Docs

Harness commands

voss
voss chat
voss do "<task>" [--no-pack]
voss edit <path>
voss doctor
voss tools
voss config
voss sessions
voss resume <session-id>

Project context and recall

voss recall <query> [--top N] [--json] [--refresh]
voss sync [--check] [--dry-run] [--force]
voss serve

voss memory size
voss memory vacuum
voss memory adopt --id <fence-id>

voss recall searches project memory and the rebuildable code recall index together. Use --refresh when you want Voss to rebuild recall state before answering. voss sync --check is read-only and exits non-zero when generated docs, managed instruction sections, or prompt files have drifted.

Compiler commands

voss check <path>
voss compile <file.voss>
voss run <file.voss>
voss init <name>
voss ast <file.voss>

Orchestration commands

Run and inspect a team — see Orchestration.

voss team check [path]              # validate .voss/team.voss (default), --json
voss team run "<goal>" [--cwd .] [--max-iterations 50]

voss board [root_id] [--cwd .]      # read-only board from persisted nodes
voss review [run_id]                # Reviewer-A + Reviewer-B per card (latest if omitted)
voss session tree <root_id> [--cwd .] [--json]

voss capabilities list [--cwd .] [--json]
voss capabilities inspect <name> [--cwd .] [--json]

voss principles show [--cwd .] [--json]

Command boundary

Need	Use
Natural-language repo task	`voss do`
Interactive agent session	`voss chat` or bare `voss`
Scoped file edit	`voss edit <path>`
Search code and project memory	`voss recall <query>`
Sync generated project instructions	`voss sync`
Check managed docs in CI	`voss sync --check`
Start the local protocol server	`voss serve`
Run a goal as a team	`voss team run "<goal>"`
Validate the team cage	`voss team check`
Inspect a team run	`voss board`, `voss review`, `voss session tree`
Execute a `.voss` file	`voss run <file.voss>`
Check `.voss` files	`voss check <path>`

Mode flags

Commands that run the harness may accept mode selection:

voss do "inspect this repo" --mode plan
voss edit src/app.py --mode edit
voss do "summarize the auth changes" --no-pack

Default modes are conservative: plan for general harness commands and edit for scoped edit sessions. --no-pack disables context packing for the run and keeps replay assembly on the legacy full-context path.

Renderer environment

Embedded hosts that run Voss inside another terminal pane can request the dense renderer with:

VOSS_RENDERER=compact voss chat
VOSS_EMBEDDED=1 voss do "summarize this repo"

VOSS_RENDERER=compact selects the compact renderer directly. VOSS_EMBEDDED=1 is an embedded-host signal only; it does not force compact mode. Embedded hosts that want the full composer can pair it with VOSS_FORCE_TUI=1.

​Harness commands

​Project context and recall

​Compiler commands

​Orchestration commands

​Command boundary

​Mode flags

​Renderer environment