> ## Documentation Index > Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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. > [!NOTE] > > 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 > [accordion] 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 ` | Install a custom `AGENT_TOOLS.md` instead of the embedded default | > > ### `liza init` flags > > | Flag | Purpose | > | - | - | > | `--spec ` | 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 | > > ```bash Global setup theme={null} > # Install Liza globally with Claude and Codex integrations > liza setup --claude --codex > > # Refresh global files after upgrading liza > liza setup --force --claude --codex > ``` > > ```bash Project initialization theme={null} > # Initialize with an interactive wizard > liza init "Build a REST API with authentication" > > # Initialize from a spec file with Claude and Codex > liza init --spec specs/vision.md --claude --codex > > # Initialize with OpenCode support > liza init "Build a CLI tool" --opencode > ``` > > ```bash Validation theme={null} > # Validate current project state > liza validate > > # Validate with verbose output for debugging > liza -v validate > > # Validate without live-process checks (for archived state) > liza validate --skip-process-checks > ``` > > > [!TIP] > > > > 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. > [accordion] 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 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 ` | Manually trigger a pipeline transition to create child tasks | > | `liza update-sprint-metrics` | Recompute and persist sprint metrics from current state | > > ### `liza get` queries > > ```bash theme={null} > liza get tasks # All tasks > liza get tasks --format table # Tabular task view > liza get tasks # 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 | > > ```bash Monitoring theme={null} > # 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' > ``` > > ```bash Lifecycle control theme={null} > # Pause before making manual edits > liza pause --reason "amending plan" > > # Resume after edits > liza resume > > # Stop agents at end of session > liza stop > > # Advance to next sprint phase (run twice: COMPLETED → archive → advance) > liza resume > liza resume > ``` > > ```bash Replanning theme={null} > # Amend planner output and replan > vim specs/plan.md > git add -A && git commit -m "amend plan" > liza replan > > # Replan a specific task > liza replan planning-task-1 > ``` > [accordion] Agent Lifecycle > > Use these commands to run agent supervisor loops, recover from crashes, and manage agent registration. > > | Command | Description | > | - | - | > | `liza agent ` | Start a supervisor loop for the given role (wraps the provider CLI) | > | `liza recover-task ` | Recover a crashed or stuck task; preserves coherent worktree by default | > | `liza recover-agent ` | 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 ` | Record a degraded health marker on an agent | > | `liza clear-agent-degraded ` | Clear a degraded health marker after manual recovery | > | `liza delete agent ` | Remove an agent entry from state (does not affect running processes) | > > ### `liza agent` flags > > | Flag | Purpose | > | - | - | > | `--cli ` | Provider to use: `claude`, `codex`, `opencode`, `gemini`, `mistral`, `kimi` | > | `--agent-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 ` | Provider to use for spawned agents | > > ```bash Starting agents theme={null} > # 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 > ``` > > ```bash Recovery theme={null} > # Recover a crashed task (preserves worktree if coherent) > liza recover-task task-42 > > # Recover and discard stale worktree > liza recover-task task-42 --fresh > > # Recover a crashed agent and respawn immediately > liza recover-agent coder-1 --cli claude > > # Repair all roles that have claimable work > liza repair-agent-pool --cli claude > ``` > > ```bash Agent identity theme={null} > # Set agent ID via environment variable > export LIZA_AGENT_ID=coder-5 > liza agent coder --cli claude > > # Override with flag (takes precedence over env var) > liza agent coder --cli claude --agent-id coder-5 > ``` > > > [!NOTE] > > > > 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. > [accordion] 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 ` | TOCTOU-safe task claim for a specific agent | > | `liza cancel-task ` | Cancel a task to ABANDONED with an audit reason | > | `liza supersede-task ` | Mark a task SUPERSEDED (replaced by other tasks or completed externally) | > | `liza mark-blocked ` | Mark a task as BLOCKED | > | `liza unblock-task ` | Restore a BLOCKED task to claimable | > | `liza assess-blocked ` | Orchestrator triage of a BLOCKED task | > | `liza assess-hypothesis-exhausted ` | Orchestrator triage of a hypothesis-exhausted task | > | `liza retarget-dependency ` | Replace a dependency edge on a non-terminal task | > | `liza reconcile-merged ` | Mark an externally merged INTEGRATION\_FAILED task as resolved | > | `liza write-checkpoint ` | Record a pre-execution checkpoint for a task | > | `liza set-task-output ` | Define structured output entries on a task | > | `liza set-discovery-disposition ` | Set the disposition of a discovered item | > | `liza delete task ` | Remove a task entry from state entirely | > > ### `liza unblock-task` flags > > | Flag | Purpose | > | - | - | > | `--reason ` | Required audit reason for the unblock | > | `--assign-to ` | Direct-resume fast path: assign to a specific agent immediately | > | `--rebase-on ` | 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 | > > ```bash Adding tasks theme={null} > # Add a single task interactively > liza add-task > > # Batch-add tasks from a JSON file > liza add-tasks tasks.json > ``` > > ```bash Blocking and unblocking theme={null} > # Mark a task blocked > liza mark-blocked task-7 > > # Unblock with a reason > liza unblock-task task-7 --reason "dependency task-6 is now MERGED" > > # Unblock and assign directly > liza unblock-task task-7 --reason "ready" --assign-to coder-1 > > # Rebase preserved worktree and unblock > liza unblock-task task-7 --rebase-on integration --reason "rebased after conflict fix" > ``` > > ```bash Dependency management theme={null} > # Replace a dependency edge > liza retarget-dependency task-9 task-3 task-10 --reason "task-3 superseded by task-10" > > # Cancel a task with a reason > liza cancel-task task-5 "scope removed in sprint review" > ``` > > > [!WARNING] > > > > 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. > [accordion] Review Workflow > > Use these commands to move tasks through the doer → reviewer cycle: submission, verdict, handoff, and release. > > | Command | Description | > | - | - | > | `liza submit-for-review ` | Doer submits completed work for review | > | `liza submit-verdict ` | Reviewer submits a verdict on submitted work | > | `liza await-verdict ` | Block the doer process until a verdict arrives | > | `liza await-resubmission ` | Block the reviewer process until the doer resubmits | > | `liza handoff ` | Structured context-exhaustion handoff; doer exits cleanly | > | `liza release-claim ` | Release doer and/or reviewer claims on a task | > | `liza update-review-commit ` | 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 | > > ```bash Doer workflow theme={null} > # 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" > ``` > > ```bash Reviewer workflow theme={null} > # Submit an approval > liza submit-verdict task-12 APPROVED > > # Submit a rejection with inline feedback > liza submit-verdict task-12 REJECTED > > # Block until doer resubmits after rejection > liza await-resubmission task-12 > > # When RESUBMITTED: review new diff and submit verdict again > liza submit-verdict task-12 APPROVED > ``` > > ```bash Claim management theme={null} > # Release a stale doer claim > liza release-claim task-12 --role coder > > # Clear all expired review leases > liza clear-stale-review-claims > ``` > [accordion] 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 ` | Create a git worktree for a claimed task in `.worktrees//` | > | `liza wt-delete ` | Delete the worktree for a completed or abandoned task | > | `liza wt-merge ` | Merge an approved task's worktree branch into the integration branch | > | `liza check-commit-allowed ` | 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. > > ```bash Worktree lifecycle theme={null} > # 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 > ``` > > ```bash Pre-commit hook theme={null} > # Install in .git/hooks/pre-commit (or via liza init) > #!/bin/sh > liza check-commit-allowed "$LIZA_CURRENT_TASK_ID" > ``` > > ```bash Orphaned worktree cleanup theme={null} > # Detect orphaned worktrees > liza validate > > # Delete an orphaned worktree > liza wt-delete task-old > > # Force-remove a stuck worktree > git worktree remove .worktrees/task-old --force > ``` > > > [!NOTE] > > > > Each task gets its own git worktree branch named `task/`. Liza tracks the `base_commit` and `review_commit` for each task in `state.yaml`. Use `liza get tasks ` to inspect these values if you need to recreate a worktree manually. ## Quick Reference > [card] First-time setup > > ```bash theme={null} > liza setup --claude --codex > liza init "Your project goal" --claude > liza agent planner --cli claude > ``` > [card] Monitor a running system > > ```bash theme={null} > liza tui # interactive dashboard > liza status # one-shot snapshot > liza analyze # circuit breaker check > ``` > [card] Recover from a crash > > ```bash theme={null} > liza recover-task > liza recover-agent --cli claude > liza repair-agent-pool --cli claude > ``` > [card] Generate a debug report > > ```bash theme={null} > liza validate > liza get tasks --format table > liza get agents --format table > cat .liza/alerts.log > ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.