Liza CLI Reference: Commands, Flags, and Workflows

Complete reference for the liza CLI binary — setup, initialization, monitoring, agent lifecycle, task management, review workflow, and worktree commands.

The liza binary is the single entry point for every interaction with Liza’s multi-agent coding system. You use it to bootstrap your environment, initialize projects, monitor running agents, manage tasks and worktrees, and perform recovery operations. All commands operate on the .liza/ directory in your project root unless otherwise noted.

Most commands support structured output via the --json flag. Pass --json to receive machine-readable results suitable for scripting, piping to jq, or integration with external tooling. Pass -v (verbose) to any command for timing details, internal operations, and richer error messages.

​

Command Groups

Setup & Initialization

Use these commands to install Liza globally and prepare individual projects before running any agents.

Command	Description
liza version	Print the binary version, commit hash, and build date
liza setup	Write global support files to ~/.liza/ and link provider integrations
liza init [description]	Initialize a project workspace and create .liza/state.yaml
liza validate [state-file]	Validate state.yaml against 43+ invariant rules
liza migrate [state-file]	Normalize role names and scrub deprecated fields from state

​

liza setup flags

Flag	Purpose
--claude	Install Claude Code skill symlinks under ~/.claude/skills/
--codex	Install Codex skill symlinks under ~/.codex/skills/
--opencode	Install OpenCode skill symlinks under ~/.config/opencode/skills/
--gemini	Install Gemini skill symlinks under ~/.gemini/skills/
--mistral	Install Mistral/Vibe prompt link under ~/.vibe/prompts/
--force	Overwrite existing global files (use after upgrading liza)
--agent-tools <path>	Install a custom AGENT_TOOLS.md instead of the embedded default

​

liza init flags

Flag	Purpose
--spec <file>	Path to a goal/vision spec file to seed the project
--claude	Activate Claude Code project hooks and settings
--codex	Activate Codex project hooks and ~/.codex/config.toml entries
--opencode	Activate OpenCode contract and install .opencode/tools/exec.ts
--force	Reinitialize even if .liza/ already exists

Global setup

# Install Liza globally with Claude and Codex integrations
liza setup --claude --codex

# Refresh global files after upgrading liza
liza setup --force --claude --codex

Run liza setup once per machine after installation or after upgrading the binary. Run liza init once per project. You do not need to rerun liza setup when starting a new project.

Monitoring & Control

Use these commands to observe system state, control agent execution, and manage sprint lifecycle.

Command	Description
liza tui	Launch an interactive TUI dashboard with live agent status and controls
liza watch	Run headless monitoring with automatic agent repair
liza status	Print a full dashboard snapshot: goal, sprint, agents, task summary
liza get <query>	Query specific state fields (tasks, agents, metrics, config fields)
liza analyze	Detect circuit-breaker patterns in anomaly history
liza pause	Pause all agents; they block without claiming new tasks
liza resume	Resume from PAUSED, CHECKPOINT, or COMPLETED sprint states
liza stop	Stop all agents cleanly; agents exit on next heartbeat
liza start	Transition system from STOPPED → RUNNING
liza sprint-checkpoint	Force a sprint checkpoint; halts agents and writes a summary
liza checkpoint	Alias for liza sprint-checkpoint
liza replan [task-id]	Invalidate planner output and create a new planning task
liza proceed <task-id> <transition>	Manually trigger a pipeline transition to create child tasks
liza update-sprint-metrics	Recompute and persist sprint metrics from current state

​

liza get queries

liza get tasks                        # All tasks
liza get tasks --format table         # Tabular task view
liza get tasks <task-id>              # Single task detail
liza get agents                       # All registered agents
liza get agents --format table        # Tabular agent view
liza get agents --zombies             # Live supervisors absent from state
liza get metrics                      # Sprint metrics
liza get config.mode                  # Current system mode
liza get sprint.status                # Current sprint status
liza get config.default_cli           # Configured default CLI

​

System modes

Mode	Agent behavior	Triggered by
RUNNING	Work and claim tasks normally	liza resume / liza start
PAUSED	Block; do not claim new tasks	liza pause
STOPPED	Exit cleanly on next heartbeat	liza stop
CIRCUIT_BREAKER_TRIPPED	Halt immediately	liza analyze or TUI auto-detection

​

liza resume behavior by sprint state

Sprint state	Condition	Effect
CHECKPOINT	Not all tasks terminal	Back to IN_PROGRESS
CHECKPOINT	All tasks terminal	Mark sprint COMPLETED
COMPLETED	—	Archive sprint, create new sprint, execute pipeline transitions

Monitoring

# Launch TUI (interactive, recommended for active sessions)
liza tui

# Print a one-shot status snapshot
liza status

# Watch tasks in real time (external watch loop)
watch -n 5 'liza get tasks --format table'

Agent Lifecycle

Use these commands to run agent supervisor loops, recover from crashes, and manage agent registration.

Command	Description
liza agent <role>	Start a supervisor loop for the given role (wraps the provider CLI)
liza recover-task <task-id>	Recover a crashed or stuck task; preserves coherent worktree by default
liza recover-agent <agent-id>	Full cleanup: release claim, remove worktree, delete agent from state
liza repair-agent-pool	Spawn agents for all roles that have claimable work but no live agent
liza mark-agent-degraded <agent-id>	Record a degraded health marker on an agent
liza clear-agent-degraded <agent-id>	Clear a degraded health marker after manual recovery
liza delete agent <agent-id>	Remove an agent entry from state (does not affect running processes)

​

liza agent flags

Flag	Purpose
--cli <name>	Provider to use: claude, codex, opencode, gemini, mistral, kimi
--agent-id <id>	Override auto-assigned agent ID (format: role-number, e.g. coder-2)
-i	Interactive mode — uses your installed provider binary directly
--no-log	Disable output logging to .liza/agent-outputs/

​

liza recover-task flags

Flag	Purpose
--fresh	Discard the task’s worktree and branch; recreate from integration
--force	Bypass live-PID checks; enables git-only cleanup when task is absent from state

​

liza repair-agent-pool flags

Flag	Purpose
--dry-run	Preview which agents would be spawned without starting them
--cli <name>	Provider to use for spawned agents

Starting agents

# Start a coder agent using Claude (auto-assigned ID: coder-1)
liza agent coder --cli claude

# Start a code-reviewer using Codex with explicit ID
liza agent code-reviewer --cli codex --agent-id code-reviewer-2

# Start a planner interactively
liza agent planner -i

Agent output logs land in .liza/agent-outputs/ as {agent-id}-{timestamp}.txt (stdout) and .err (stderr). Use liza -v or inspect these files to diagnose agent behavior. Sensitive values matching patterns like *_API_KEY or *_TOKEN are automatically masked in persisted logs.

Task Management

Use these commands to add, cancel, block, unblock, and modify tasks in the blackboard.

Command	Description
liza add-task	Add a single task to state interactively
liza add-tasks	Batch-add tasks from a JSON file
liza claim-task <task-id> <agent-id>	TOCTOU-safe task claim for a specific agent
liza cancel-task <task-id> <reason>	Cancel a task to ABANDONED with an audit reason
liza supersede-task <task-id>	Mark a task SUPERSEDED (replaced by other tasks or completed externally)
liza mark-blocked <task-id>	Mark a task as BLOCKED
liza unblock-task <task-id>	Restore a BLOCKED task to claimable
liza assess-blocked <task-id>	Orchestrator triage of a BLOCKED task
liza assess-hypothesis-exhausted <task-id>	Orchestrator triage of a hypothesis-exhausted task
liza retarget-dependency <task-id> <old> <new>	Replace a dependency edge on a non-terminal task
liza reconcile-merged <task-id>	Mark an externally merged INTEGRATION_FAILED task as resolved
liza write-checkpoint <task-id>	Record a pre-execution checkpoint for a task
liza set-task-output <task-id>	Define structured output entries on a task
liza set-discovery-disposition <disc-id> <disp>	Set the disposition of a discovered item
liza delete task <task-id>	Remove a task entry from state entirely

​

liza unblock-task flags

Flag	Purpose
--reason <text>	Required audit reason for the unblock
--assign-to <agent-id>	Direct-resume fast path: assign to a specific agent immediately
--rebase-on <branch>	Rebase the preserved worktree onto the given integration branch
--allow-dirty	Allow rebase with tracked worktree changes (uses git autostash)

​

Task status reference

Status	Claimable	Terminal
DRAFT_CODE	Yes	No
IMPLEMENTING_CODE	No	No
CODE_TO_REVIEW	No (reviewable)	No
CODE_REJECTED	Yes	No
MERGED	No	Yes
BLOCKED	No	No
ABANDONED	No	Yes
SUPERSEDED	No	Yes
INTEGRATION_FAILED	Yes	No

Adding tasks

# Add a single task interactively
liza add-task

# Batch-add tasks from a JSON file
liza add-tasks tasks.json

Never edit .liza/state.yaml by round-tripping it through a YAML serializer (Python’s yaml.dump, Ruby’s YAML, etc.). The file is owned by Go’s yaml.v3. Use Liza CLI commands wherever possible; for unsupported edits, use line-level text operations only. Always run liza validate after any manual edit.

Review Workflow

Use these commands to move tasks through the doer → reviewer cycle: submission, verdict, handoff, and release.

Command	Description
liza submit-for-review <task-id>	Doer submits completed work for review
liza submit-verdict <task-id> <APPROVED|REJECTED>	Reviewer submits a verdict on submitted work
liza await-verdict <task-id>	Block the doer process until a verdict arrives
liza await-resubmission <task-id>	Block the reviewer process until the doer resubmits
liza handoff <task-id> <summary> <next-action>	Structured context-exhaustion handoff; doer exits cleanly
liza release-claim <task-id>	Release doer and/or reviewer claims on a task
liza update-review-commit <task-id>	Update the review boundary to the current worktree HEAD
liza clear-stale-review-claims	Clear all expired review leases across the project

​

liza await-verdict exit actions

Result	Doer action
APPROVED	Exit normally; do not run further worktree commands
REJECTED	Fix issues and resubmit (session stays alive — no cold restart)
ALREADY_TRANSITIONED	Follow safe_action field: stop = exit; revise = you still own it
NEW_ATTEMPT / TIMEOUT / ABORTED	Exit normally

​

liza await-resubmission exit actions

Result	Reviewer action
RESUBMITTED	Review the new changes (session stays alive)
TERMINAL / TIMEOUT / ABORTED	Exit normally

Doer workflow

# Submit work for review
liza submit-for-review task-12

# Block until verdict arrives
liza await-verdict task-12

# If REJECTED: fix, commit, resubmit
# ... make fixes ...
git add -A && git commit -m "fix review feedback"
liza submit-for-review task-12

# Handoff when approaching context limit
liza handoff task-12 "Implemented auth middleware, tests pass" "Review session middleware ordering"

Worktree Management

Use these commands to create, merge, and delete the git worktrees that give each task an isolated workspace.

Command	Description
liza wt-create <task-id>	Create a git worktree for a claimed task in .worktrees/<task-id>/
liza wt-delete <task-id>	Delete the worktree for a completed or abandoned task
liza wt-merge <task-id>	Merge an approved task’s worktree branch into the integration branch
liza check-commit-allowed <task-id>	Exit 0 (allow) or 1 (reject) — used in git pre-commit hooks

Worktrees are bare checkouts. If your project requires build artifacts (e.g. node_modules/, vendor/), configure post_worktree_cmd in the config section of .liza/state.yaml to run a shell command after every worktree creation.

Worktree lifecycle

# Create a worktree for a task you just claimed
liza wt-create task-12

# Work in the isolated worktree
cd .worktrees/task-12
# ... make changes, run tests, commit ...

# After approval: merge to integration branch
liza wt-merge task-12

# Clean up a terminal task's worktree
liza wt-delete task-12

Each task gets its own git worktree branch named task/<task-id>. Liza tracks the base_commit and review_commit for each task in state.yaml. Use liza get tasks <task-id> to inspect these values if you need to recreate a worktree manually.

​

Quick Reference

First-time setup

liza setup --claude --codex
liza init "Your project goal" --claude
liza agent planner --cli claude

Monitor a running system

liza tui          # interactive dashboard
liza status       # one-shot snapshot
liza analyze      # circuit breaker check

Recover from a crash

liza recover-task <task-id>
liza recover-agent <agent-id> --cli claude
liza repair-agent-pool --cli claude

Generate a debug report

liza validate
liza get tasks --format table
liza get agents --format table
cat .liza/alerts.log