# CLI The installed command is `aw`. Run `aw --help` and `aw --help` for the current argument contract. Both are successful display commands. In a source checkout, use `node bin/aw-debug.js` for current-source evidence. ## Project setup - `aw init "summary"` initializes or reconciles the project workspace. - `aw install --target agents` installs project skills in `.agents/skills/`. - `aw install --target claude-code` installs Claude Code skills. - `aw install --target codex` installs the legacy Codex compatibility target. - `aw check [task-id]` validates workflow structure. With no task id it runs the complete project-wide structural report. With an explicit task id it uses fixed lifecycle probes and validates only that task's durable directory, registered artifacts, nested agent sidecars, and local consistency rules. `aw repair`, dashboard health, and TUI health remain project-wide. ## Tasks and artifacts - `aw create "intention"` creates a task record for lower-level automation. - `aw status [task-id]` reports project or task state. - `aw next [task-id]` reports the next recorded action. - The explicit task-id forms use bounded probes of the fixed lifecycle paths and read only that task's direct artifacts. The no-id forms intentionally build a project-wide inventory for global status and routing. - `aw render --for ` renders step context. - `aw read` and `aw write` access registered task artifacts. - `aw step todo set --stdin` atomically replaces the running step's complete ordered todo list. Input is a strict object with unique bounded `id`, bounded `title`, and `todo|doing|done` status rows; at most one row may be `doing`. A tracked step requires a non-empty all-done list before completion. Execute instead derives completion from approved plan rows and titled execution-only deviation rows. - `aw task move|cancel|reactivate|rollback` owns lifecycle mutations. For normal agent-driven work, prefer `$aw-task` and `$aw-resume`; the skills add roadmap association, step protocols, gates, and closure behavior around these CLI primitives. ## Project guidance - `aw guidance` expands dynamic step or skill guidance. - `aw roadmap` reads and mutates phase/item state. - `aw blueprint-update` records task feedback candidates. - `aw knowledge` adds or loads retained knowledge. - `aw docs` discovers project and task documentation surfaces. - `aw guidance` also injects the absolute directory of the version-matched product docs shipped with the installed package; agents can read detailed CLI, skill, and artifact references there without guessing npm layout. ## Services and inspection - `aw server` supervises enabled core background services. - `aw agent-server` and `aw index-server` expose individual lifecycle status. - `aw dashboard start` explicitly enables the local dashboard service. - `aw tui` launches the read-only terminal inspector. - `aw observe activity [task-id] [--goal-scope ]` returns bounded context for status integrations. Without a task id it returns only the nearest Weyaw project display name and never selects or lists repository tasks. An explicit project-bound task returns its roadmap title, lifecycle, effective step, and one normalized `current_step` detail containing ordered `todo|doing|done` rows plus `completed` and `total`. Analyze, Plan, Verify, and Review project their durable step todos; Execute projects approved plan rows plus titled execution-only deviation rows from `execution.json`. A caller-supplied aw-goal stage or ordered item scope adds only one-based current/total position. Agent rows are task-scoped and expose only bounded title, AGT-R/AGT-X mode, status, content-token usage/budget, turn and attempt counts, and optional group position. Bounded terminal rows may be returned for presentation, but only queued/running agents drive activity polling. Prompts, complete objectives, outputs, events, paths, model/adapter data, health, service state, and mutation controls are omitted. - `aw index` reports or queries local project/workflow index state. - `aw index source-map` projects compact structural roles published with each active index generation. It never walks source corpora at query time. A corpus reports `available: false` with warnings while unbuilt, dirty, backlogged, refreshing, or migrating; `scanned_files` is the number of files classified in that published generation, not a query-time scan count. `explore-plan` continues with ready lexical search evidence and does not reconstruct the map in the foreground. - Manifest/source-map schema upgrades are performed by index-server background reconciliation or explicit index administration, not by normal task steps. Long-running lifecycle commands require a host environment that can retain processes; ordinary reads, status, guidance, roadmap, and artifact commands do not. ## Official Agent dispatch Weyaw ships a version-matched official Agent trigger registry. Project config may enable or disable recognized ids, select worker order, and narrow turn, fan-out, or content-token limits within bundled ceilings. `extensions/agents.json` may override behavior prose for recognized ids only; local trigger creation and safety-field overrides are rejected. Use `aw agent readiness --json` before trigger-aware dispatch. A task request names `--task`, its recorded `--step`, `--trigger`, capability, roots, targets, and resource keys. A non-task request names an optional `--operation`, `--context`, and `--trigger`; readiness allocates an operation id when omitted. Readiness returns the resolved context, owner, workdir, canonical write roots, recovery decision, and resource conflicts. - Task writers are bound to the task's frozen worktree. Brainstorm, Analyze, and Execute official project contributors require explicit project-relative `--write-root` values outside the artifact root. - Non-task read-only reasoning keeps jobs and session sidecars under `.aw/.runtime/agent-server/operations//` and does not create a task. - `control.aw-cli-chain` is the only official non-task writer. It matches `weyaw.operation.aw-cli` and may open one temporary broad `aw **` capability. The harness runs in the common sandbox with project and workflow files read-only; AW invocations are proxied, recorded, and followed by Host reread. - `aw agent submit` requires exactly one `--task` or `--operation`. Trigger-aware submit repeats the readiness policy immediately before persistence. - `aw agent group start` accepts the same owner forms. Every assignment names its official trigger; group manifests are written before members, interrupted publication converges to a terminal canceled remainder, and dead-owner control locks are recovered with PID/start-identity evidence. - Use `aw agent group status|join|cancel|retry --task ...` for task groups or the corresponding `--operation ` form for runtime-operation groups. ## Agent progress monitoring - `aw agent monitor --job [--since-line ]` reads one job's identity, adapter, token, timing, progress, and finished-state evidence, plus the progress events after ``. - Add `--wait` only in job mode to block without mutation until the original complete-line cursor has at least one unread event or the authoritative job is `finished`. The command then returns exactly one ordinary monitor report. - `aw agent monitor --group --task [--assignment-since-line =]` reads the same evidence per group assignment; the flag is repeatable because members advance independently. Group monitoring remains single-shot and rejects `--wait`. - `aw agent mcp` runs a foreground, project-bound MCP server over newline-delimited stdin/stdout. It exposes one read-only `agent_monitor` tool with `job_id`, optional `since_line`, and optional `wait`, plus resources at `weyaw://agent/jobs/`. Tool and resource reads return the same authoritative `AgentServerMonitorReport` used by the CLI monitor. Without `--wait`, each job or group call performs one bounded read and exits. A waiting job rereads from the caller's original cursor every 100 ms, retains no read handle or lock between polls, and never advances a private cursor. Carry the returned `next_line` into a later call to receive only unseen events; omitting the cursor returns the full history. Only newline-terminated progress records wake the command. A finished job also wakes immediately even when the event delta is empty, so the response need not include a later `finalized` event. There is no built-in deadline or timeout result; interrupt a wait by terminating the CLI process. MCP supports both `resources/subscribe` / `resources/unsubscribe` and MCP 2026-07-28 `subscriptions/listen`. Each active job subscription owns one connection-local background wait loop. The loop establishes the current `next_line` as its baseline, re-arms the same bounded job wait after each wake, and sends only standard `notifications/resources/updated` messages naming the resource URI. Notifications are wake hints, not event delivery: reread the resource or call `agent_monitor` to obtain authoritative state. A loop stops on job `finished`, unsubscribe or request cancellation, connection close, or server shutdown. Subscriber cursors are never persisted. The adapter does not expose groups, mutation tools, MCP Tasks, custom notifications, or HTTP transport, and it does not wait for a later `finalized` event. Stop when `finished` is true. An out-of-range cursor is an error rather than an empty result, because it means a retry reset the progress log. The durable `turn_finished` progress event marks the useful intermediate point where one provider turn's record, assistant message when present, and observed changes are already persisted. Its evidence contains only `turn_id`, `turn_status`, and `output_available`. It may arrive before the job itself is `finished`; it is a cursor wake fact, not a separate result-publication state. A group report carries two finished-state flags because they answer different questions. Stop polling on `finished`, which follows job status and guarantees each assignment's `finished_evidence` is present. `turns_finished` means only that every member's provider turn finished while the jobs are still being collected; it is what `aw agent group join` acts on, not a stop signal. A group member whose job is finished while its turn is not appears in `stuck_turns`: its outcome comes from the job status, and `finished` already accounts for it. See [Getting Started](getting-started.md) and [Dashboard](dashboard.md).