Skip to content
warden
Blog

CLI command reference

{/* Code-generated by cmd/gendocs from the warden cobra command tree. DO NOT EDIT. Regenerate with make gendocs after changing any command’s Use/Short/Long or flags; CI (make gendocs-check) fails the build if this file is stale. */}

Every warden command and its flags, walked straight from the live cobra command tree, so this page can never drift from the actual --help output.

All commands accept --addr to point at a non-default daemon (overrides the addr config setting) and --config to point at a non-default config file (default ~/.warden/config.yaml). <TICKET> is the agent ID — a Jira key for managed agents, or an agent-xxxx ID for prompt-spawned ones.

warden

Section titled “warden”
spawn, monitor, and tear down AI coding agent sessions.
Run `warden` with no arguments to open the cockpit TUI. Alias: wd.


Usage:
  warden [command]
  warden [flags]


Run work:
  agent                Create, inspect, communicate with, and manage agents
  pipeline             Define and run DAG pipelines of agent jobs
  plan                 Manage plans tracked by the daemon
  autopilot            Show autopilot status and land worker branches
  schedule             Schedule recurring (--cron) or single-shot (--at) agents and pipelines


Work with a project:
  project              Manage repo-local warden configuration: memory, presets, templates, and plugins
  projects             Inspect and manage daemon-registered projects
  project-groups       Inspect and manage project groups and membership
  workspace            Inspect and manage warden git worktrees, snapshots, branches, and file collisions
  git                  Commit, push, sync, and review an agent worktree on warden rails
  check                Run project checks and install hook guards


Coordinate:
  context              Read and write the shared context (a namespaced key/value store agents share)
  message              Send and receive directed messages between agents
  approval             Manage tool-permission prompts and auto-approve policy


Observe and configure:
  inspect              Search, audit, export, repair, and measure warden's fleet and resources
  backend              Inspect and manage the agent-backend registry
  usage                Show provider usage for subscription backends
  config               Show the resolved configuration (and its file path)


Operate warden:
  daemon               Run the warden hub (HTTP API + poller; the single writer to the file store)
  completion           Generate shell completion scripts
  factory-reset        Reset warden to a fresh-install state (scoped wipe of daemon data)
  bug-report           Review a staged crash draft and, only if you approve, file it as a GitHub issue


Get started and interact:
  login                Authenticate this node with a warden-hub relay using the device flow
  setup                Install missing dependencies (tmux, git, claude; optional gh)
  init                 Initialize the Warden data directory and schema ledger
  tutorial             Run the first-run guided walkthrough of warden's core loop
  doctor               Run preflight checks (required binaries, daemon, data dir, agent store, backend registry integrity)
  tui                  Live terminal cockpit for agents
  update               Update the installed warden binary from GitHub Releases
  migrate              Inspect, apply, resume, or restore data format migrations
  rollback             Roll back the previous warden update
  version              Print warden version and build information


Shortcuts:
  start                Spawn an agent — `start --role <ROLE> "<prompt>"` (free-form), `start --role <ROLE> --dir <path>` (interactive), or `start --role worker --repo <PATH>` (managed worktree)
  ls                   List all active agent sessions
  status               Show full status for one session
  send                 Type a message into an agent's AI CLI session and press Enter
  commit               Stage and commit the worktree (warden rails + hooks + bookkeeping)
  push                 Push the current branch to origin (warden rails + bookkeeping)
  sync                 Fetch and rebase the current branch onto its base (warden conflict detect)
  release              Recommend the next SemVer release tag, then tag and push it on confirmation


Use "warden help <command>" for focused command help; add --all for the complete tree.

warden agent

Section titled “warden agent”
Create, inspect, communicate with, and manage agents.


Wherever a command takes <AGENT>, it is the agent's name, id or ticket as shown
by 'warden ls'.


Teardown: 'stop' is the full teardown (terminate the session, clear the record,
remove the worktree and branch) and takes --keep-worktree, --keep-record, --hard
and --pr to keep parts. 'terminate' only kills the session, keeping the record
and worktree. The narrower 'done', 'delete' and 'remove-worktree' verbs still work
but are hidden; see 'warden help agent stop'.


Usage:
  warden agent [flags]


Commands:
  list                 List all active agent sessions
  start                Spawn an agent — `start --role <ROLE> "<prompt>"` (free-form), `start --role <ROLE> --dir <path>` (interactive), or `start --role worker --repo <PATH>` (managed worktree)
  status               Show full status for one session
  digest               Summarize what an agent accomplished (files, branch, turns, narrative)
  fork                 Fork an agent's session into a new managed agent (branches the conversation; the source keeps running)
  restore              Recreate and resume a lost/orphaned agent (resumes its AI CLI session)
  recover              Revive archived orphaned agent records whose tmux session is still alive (dry run unless --apply)
  adopt                Register the AI CLI session in this directory (resume it under tmux, or register the current tmux session live)
  attach               Attach to the agent's or terminal's live session
  stop                 Tear down an agent (default: terminate + clear record + remove worktree; --keep-* flags keep parts)
  terminate            Stop an agent: kill its tmux+AI CLI session (keeps the record and worktree)
  send                 Type a message into an agent's AI CLI session and press Enter
  tail                 Print the recent output of an agent's AI CLI session
  handoff              Hand off work: delegate to a new/existing agent (--to), or retire self into a successor (--retire)
  rotate               Retire this agent and hand its work to a fresh successor in the same workspace (alias for `warden agent handoff --retire`)
  switch               Hot-swap an agent session to a different AI CLI, model, or tier mid-task
  set                  Change one per-agent setting (including permission-posture)
  get                  Show one or all per-agent settings, including permission-posture
  role                 Inspect warden's built-in agent roles and tier mappings


Flags:
  -h, --help   help for agent


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent list

Section titled “warden agent list”
List all active agent sessions


Usage:
  warden agent list [flags]


Flags:
  -a, --all           include system agents
  -h, --help          help for list
      --json          output as JSON
      --tag strings   only show agents carrying every given tag (repeatable or comma-separated, e.g. --tag backend --tag urgent)
  -w, --watch         live-update the list on every agent state change (Ctrl+C to exit)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent start

Section titled “warden agent start”
Spawn an agent. --role is required (see 'warden agent role list'); there is no
implicit fallback role.


Spawn modes:
  Free-form    warden agent start --role <ROLE> "<prompt>" [--dir <path>]
               Autonomous: runs the prompt in --dir (default: current directory).
  Interactive  warden agent start --role <ROLE> --dir <path>
               No prompt: opens the agent and waits for you.
  Managed      warden agent start --role worker --repo <PATH> [TICKET]
               Isolated git worktree off --repo (worker role + --repo).
  Terminal     warden agent start --kind terminal --dir <path>
               Not an AI agent: a plain shell ($SHELL) in --dir, with the same
               worktree/git/tmux lifecycle. --aicli/--model/--role/prompt are ignored.


Which AI CLI + model runs (first match wins):
  1. --aicli + --model         explicit pin (--model requires --aicli)
  2. --aicli alone             optimal model for that AI CLI at the tier
  3. --tier (or --task)        quota-balanced resolver at that tier
  4. --role alone              resolver routed by the role's tier
  5. configured defaults
So --role on its own is always enough; --tier/--aicli/--model only refine it.


Accepted --aicli values: claude (default), aider, opencode, codex, crush, goose,
cursor, antigravity. Per-AI-CLI behaviour (model, resume, spend fidelity) and
maturity labels: see 'warden backend --help'.


Usage:
  warden agent start --role <ROLE> [TICKET|"<prompt>"] [--repo <PATH>] [--dir <PATH>] [--aicli <ID>] [flags]


Flags:
      --aicli <ID>                  AI CLI <ID>: claude (default, stable) | aider | opencode | codex | crush | goose | cursor | antigravity — only claude is fully tested; codex/antigravity are beta, the rest experimental. See 'warden backend --help' for per-AI-CLI notes
      --auto-restart                auto-resume this agent if it crashes (errored), capped at a few attempts
      --branch string               new branch (development) or checkout target (pr-review)
      --dir string                  directory to launch the agent from (default: current directory)
      --force                       spawn even when the memory-pressure gate warns
      --fork-from <AGENT>           fork the existing agent <AGENT>'s recorded session into this new managed agent (codex's native fork): branches the source's conversation in a fresh sibling worktree off its branch, carrying its uncommitted tracked changes; the source keeps running. Uses --role worker when the chosen role does not own a worktree; the fork inherits the source's repo+backend. See 'warden agent fork' for the shorthand
  -h, --help                        help for start
      --in-repo                     managed spawns only: opt out of isolation and run in the shared --repo checkout instead of a worktree (ignored for pr-review; overridden when root_guard is on)
      --json                        emit the new agent (id, name, role, ai_cli, model, workdir) as JSON
      --kind string                 session kind: empty/agent (default) spawns an AI agent; terminal opens a plain interactive shell ($SHELL) in --dir (not an AI agent — --aicli/--model/--role/prompt ignored)
      --model string                model ID for the chosen AI CLI (requires --aicli). Empty lets the tier resolver pick an explicit model
      --name string                 explicit agent name (omit to auto-resolve); max 32 chars, alphanumeric + hyphens/underscores
      --permission-mode string      permission mode: acceptEdits|auto|bypassPermissions|default|dontAsk|plan (default: from config or 'auto')
      --permission-posture string   Warden prompt authority: read-only|read-write|allowlisted|dangerously-execute-all (default: role/config/legacy-mode mapping)
      --plan string                 optional planstore plan id in the same project (plan-<8hex>); empty = planless agent. A non-empty value must name an existing plan belonging to the resolved project
      --pr string                   PR number/url (pr-review)
      --preset <NAME>               load saved spawn defaults from the named preset <NAME> (see 'warden project preset'); explicit flags override
      --project <ID>                <ID> of the daemon project this agent joins (its canonical path or remote URL, from 'warden projects list'); stamps membership explicitly instead of leaving the daemon to path-match the launch dir. Empty = the git repository root of the launch directory (the daemon auto-registers it)
      --prompt-template <NAME>      fill the saved prompt template <NAME> (see 'warden project prompt-template') as the spawn prompt; a positional prompt still wins
      --repo string                 repo path for a managed spawn: with --role worker, picks an isolated worktree off this repo (the default managed mode; branch it with --branch). Empty = free-form unless --fork-from forces managed (then defaults to cwd)
      --role <ROLE>                 REQUIRED — built-in agent role <ROLE>: general | autopilot | brain | orchestrator | planner | worker (legacy aliases implementer/auto-merger/reviewer resolve to worker). Injects the role's persona as a system-prompt addendum and applies its default flags. See 'warden agent role list'
      --set stringArray             supply a prompt-template variable as VAR=value (repeatable, e.g. --set FILE=foo.go --set X=y)
      --tags <LIST>                 comma-separated labels <LIST> for grouping/filtering (e.g. --tags backend,urgent); searchable and filterable via 'warden agent list --tag'
      --task string                 task name (task registry) used to derive the model tier when --tier is empty. Empty = none
      --tier string                 model tier for the quota-balanced resolver that picks the AI CLI+model: tier-1|tier-2|tier-3. Empty derives the tier from --task, then --role (--role is required, so this always has a role to derive from). An explicit --aicli/--model still wins over the resolver
      --worktree                    managed spawns only: use a throwaway scratch worktree instead of a branch worktree (analysis/spike). Neither --worktree nor --in-repo = the normal isolated branch worktree


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent status

Section titled “warden agent status”
Show full status for one session


Usage:
  warden agent status <AGENT> [flags]


Flags:
  -h, --help   help for status
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent digest

Section titled “warden agent digest”
Summarize what an agent accomplished (files, branch, turns, narrative)


Usage:
  warden agent digest <AGENT> [flags]


Flags:
  -h, --help   help for digest
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent fork

Section titled “warden agent fork”
Fork an existing agent's recorded session into a NEW warden-managed agent.


A fork branches the source agent's conversation/reasoning (codex's session rollout)
into a divergent session and continues it as its own managed agent: a fresh sibling
worktree off the source's branch HEAD, seeded with the source's uncommitted tracked
changes (dirty-tree carry), with its own tmux session warden monitors and tears
down. The source agent keeps running, untouched — fork branches sideways, unlike
snapshot (rewinds one timeline) or rotate/handoff (carry the task, drop the
conversation).


This is the shorthand for `warden agent start --fork-from <AGENT>` — a managed spawn
whose launch command is the backend's fork verb. Only backends with a native session
fork are forkable (codex today); forking one without (e.g. claude) reports a clean
"cannot fork". The source's backend session id must already be pinned — if it has not
run a turn yet the fork reports that, and you retry once it has.


NOTE: `git stash create` carries only TRACKED changes; the source's untracked /
.gitignore'd build artifacts are not seeded into the fork.


  warden agent fork agent-7                  fork agent-7, continue its conversation
  warden agent fork agent-7 "now try X"      fork and seed a divergent first prompt


Usage:
  warden agent fork <AGENT> ["<prompt>"] [flags]


Flags:
      --force                    fork even when the memory-pressure gate warns
  -h, --help                     help for fork
      --json                     emit the forked agent (id, name, role, ai_cli, model, workdir) as JSON
      --model string             model override for the fork (default: the source/backend default)
      --name string              optional human-friendly name for the fork
      --permission-mode string   permission mode for the fork: acceptEdits|auto|bypassPermissions|default|dontAsk|plan (default: from config)
      --role string              built-in role for the fork (default worker — owns a worktree) (default "worker")


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent restore

Section titled “warden agent restore”
Use when warden still has the agent's record but its tmux session is gone
(orphaned: reboot, killed tmux server, crash). Recreates the tmux session in the
agent's original workdir and resumes the same AI CLI conversation. Resume-only:
it refuses rather than start a fresh conversation (e.g. backend cannot resume,
no pinned session id, workdir or transcript missing) and refuses while the tmux
session is still alive.


Not this command?
  warden agent recover   archived orphaned records whose tmux session is still alive
  warden agent adopt     a session warden never managed


Usage:
  warden agent restore <AGENT> [flags]


Flags:
  -h, --help   help for restore


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent recover

Section titled “warden agent recover”
Use when an agent vanished from the list but its tmux session is still running
(the record was archived by mistake) — it brings the record back; it never
relaunches anything. If the tmux session is gone, use `warden agent restore`;
for a session warden never managed, use `warden agent adopt`.


Scans archived (closed) agent records for ones whose status is orphaned
(the only recovery source) and whose tmux session is confirmed still alive
— a live session's record should never end up archived, but a stale orphaned
status racing a daemon restart could previously slip one past the tombstone
reaper. Bare `wd agent recover` only reports what it finds; --apply re-inserts each
candidate into the active store under its original id. Any children (linked
via parent_id, untouched by archiving) reconnect automatically — no need to
recover them separately.


--apply is a dry-run switch (report vs. act), not a confirmation, so it is
intentionally NOT --yes.


Usage:
  warden agent recover [flags]


Flags:
      --apply   actually re-insert candidates (default: report only); a dry-run switch, not a --yes confirmation
  -h, --help    help for recover
      --json    output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent adopt

Section titled “warden agent adopt”
Use for an AI CLI session warden never spawned or tracked — no existing record.
Registers it and returns a new warden agent id. Run from inside a tmux session it
adopts that session live (no relaunch); otherwise it resumes the newest session
for --dir (or --session-id) under a fresh tmux session.


Not this command?
  warden agent restore   a known warden record whose tmux session is gone
  warden agent recover   archived orphaned records whose tmux session is still alive


Usage:
  warden agent adopt [flags]


Flags:
      --dir string          directory whose AI CLI session to adopt (default: current directory)
  -h, --help                help for adopt
      --session-id string   AI CLI session id to adopt (default: newest for the directory)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent attach

Section titled “warden agent attach”
Attach your terminal to a running session.


A plain terminal hosted on warden's own PTY runtime (runtime.pty: on) is attached
natively: your terminal goes raw so Ctrl-C, Ctrl-D, Ctrl-Z and full-screen
programs behave exactly as in a local shell, the replay and live output are
ordered without gaps, and you hold the session's controller lease. Press Ctrl-]
then '.' to detach (the shell keeps running), Ctrl-] then 't' to take control
back if another client took it, Ctrl-] Ctrl-] to send a literal Ctrl-].
Set WARDEN_ATTACH=observe to watch read-only, or WARDEN_ATTACH=tmux to skip the
native attach. Set WARDEN_ATTACH_DETACH_KEY to a single byte (for example
"^]" is the default Ctrl-]) to change the detach chord. Replayed output and
snapshots are redacted text; only a live interactive stream carries exact bytes.


Every other session (agents, tmux-hosted terminals) attaches with tmux as before.


Usage:
  warden agent attach <AGENT> [flags]


Flags:
  -h, --help   help for attach


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent stop

Section titled “warden agent stop”
Stop an agent: the default, full teardown.


<AGENT> is any identifier `wd ls` shows — the agent's name, its id, or its
ticket.


By default `wd agent stop <AGENT>` terminates the tmux+AI CLI session, clears
(archives) the record, and removes the git worktree + branch (asking for
confirmation first, unless --yes). Keep parts around with:


  --keep-worktree   leave the git worktree and branch in place
  --keep-record     leave the stored record in place
  --hard            purge the record instead of archiving it
  --pr              open a GitHub PR first, while the agent is still intact


Safe ordering is always: PR -> terminate -> remove worktree -> clear record, so
a failed push leaves the agent running and a failed worktree guard (alive /
dirty / unpushed) leaves the record intact and the call retryable. A failure
reports which steps already ran.


To only kill the session and keep everything else, use
`wd agent terminate <AGENT>` (same as stop --keep-record --keep-worktree).


Older verbs (hidden, still work; not all are expressible as stop flags):


  wd agent done <A> [--hard|--pr]  terminate + clear record, worktree kept
                                   (stop --keep-worktree [--hard|--pr])
  wd agent delete <A> [--hard]     clear the record ONLY; does not terminate
                                   (no stop equivalent)
  wd agent remove-worktree <A>     remove the worktree + branch ONLY; does not
                                   terminate (no stop equivalent)


Usage:
  warden agent stop <AGENT> [flags]


Flags:
      --base string             base branch for the PR (default main); only meaningful with --pr
      --delete-adopted-branch   also delete the branch even if warden did not create it (adopted branches are kept by default)
      --force                   override the alive/uncommitted/unpushed worktree guards
      --hard                    purge the record instead of archiving
  -h, --help                    help for stop
      --json                    emit the teardown result (id, steps that ran) as JSON; never prompts — remove-worktree needs --yes
      --keep-record             do not clear the stored record
      --keep-worktree           do not remove the git worktree and branch
      --pr                      open a GitHub PR for the agent's branch (pushes first; title+body from the digest) before tearing down
      --yes                     skip the worktree-removal confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent terminate

Section titled “warden agent terminate”
Stop an agent: kill its tmux+AI CLI session (keeps the record and worktree).


Terminating the manager of an active autopilot run is not a stop: the guardian
respawns it in the same slot. To stop a run use `wd plan pause` or `wd plan stop`.


Usage:
  warden agent terminate <AGENT> [flags]


Flags:
  -h, --help   help for terminate
      --json   emit the teardown result (id, steps that ran) as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent send

Section titled “warden agent send”
Type a message into an agent's AI CLI session and press Enter


Usage:
  warden agent send <AGENT> <message...> [flags]


Flags:
  -h, --help   help for send


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent tail

Section titled “warden agent tail”
Print the recent output of an agent's AI CLI session


Usage:
  warden agent tail <AGENT> [flags]


Flags:
  -h, --help        help for tail
      --lines int   number of pane lines to capture (default 200)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent handoff

Section titled “warden agent handoff”
Hand a structured context package off to another agent. Phase 1 (writing the handoff file + resume prompt) is driven by the /warden skill; this verb performs the delivery. Three modes:


  • default — spawn a fresh delegate in its own isolated worktree for a sub-task; the source agent keeps running.
  • --to <id> — deliver the handoff into an already-running agent's inbox (waking it); the source agent keeps running.
  • --retire — spawn a successor in THIS agent's SAME worktree, then reap the calling agent (self-succession). Requires --yes. This is what the `warden agent rotate` alias runs.


--retire and --to are mutually exclusive: retire reaps the caller, --to never does.


Usage:
  warden agent handoff [flags]


Flags:
      --as string              act as this agent id for provenance (defaults to $WARDEN_SESSION_ID, else 'human')
      --branch string          optional branch for a new delegate (ignored with --to)
      --force                  spawn the new delegate even when the memory-pressure gate warns (ignored with --to)
  -h, --help                   help for handoff
      --json                   emit the result as JSON (new delegate: id, name, role, ai_cli, model, workdir; --to: to, from, woke)
      --name string            optional human-friendly name for a new delegate (ignored with --to)
      --repo string            repo for a new delegate (default: source agent's repo, else cwd; ignored with --to)
      --resume-file string     path to the handoff notes file whose content is delivered to the recipient (with --retire, the path the successor reads in place)
      --resume-prompt string   the recipient's task prompt
      --retire                 self-succession: spawn a successor in THIS agent's worktree and reap the calling agent (mutually exclusive with --to; requires --yes). Equivalent to 'warden rotate'
      --role string            built-in role for a new delegate (ignored with --to) (default "worker")
      --to string              deliver to this existing agent id instead of spawning a new one
      --yes                    with --retire, confirm: actually spawn the successor and retire this agent (required)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent rotate

Section titled “warden agent rotate”
Run inside an agent session. Phase 1 is driven by the /warden skill (the agent writes a handoff file + resume prompt and shows you). On your go-ahead, run with --yes to spawn the successor and reap this agent.


This is a thin alias for `warden agent handoff --retire` — the unified handoff verb's self-succession mode. Both run the identical code path.


Usage:
  warden agent rotate [flags]


Flags:
  -h, --help                   help for rotate
      --resume-file string     path to the handoff notes file the successor reads (use a unique per-agent path, e.g. $TMPDIR/warden-rotate-handoff-$WARDEN_SESSION_ID.md, so concurrent rotations don't clobber each other)
      --resume-prompt string   the successor's initial task prompt
      --yes                    confirm: actually spawn the successor and retire this agent (required for retire)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent switch

Section titled “warden agent switch”
Mid-session hot-swap: retire the active CLI process and launch a successor AI CLI
in the SAME worktree, carrying forward structured context (Goal, Decisions Log,
Modified Files Diff, Immediate Next Step) so the new agent continues without starting cold.


The successor can be chosen by explicit --aicli and/or --model, or by --tier
(resolved via quota-balanced weighted headroom routing across eligible AI CLIs).
--model requires --aicli. --role only selects the tier to resolve from; it does not
change the agent's role (see 'warden agent set <AGENT> role').


With --aicli and no --model, the model is picked from the accepted model catalog
within that AI CLI, at --tier, else --role's tier, else the agent's own role tier;
it never keeps the old pin, widens the tier or uses a paid route, and the swap is
refused (the running CLI is left alone) when no candidate is eligible. Refresh the
catalog first with 'warden models refresh --apply --yes'. An explicit --aicli plus
--model is launched exactly as given.


The swap is performed by the warden daemon (the sole owner of the session store),
so the daemon must be running.


Examples:
  warden agent switch --aicli antigravity --model gemini-3.1-pro
  warden agent switch --aicli codex            (catalog pick in codex at the agent's role tier)
  warden agent switch --tier tier-1
  warden agent switch abc123 --tier tier-3 --prompt 'Focus on unit test coverage'




Usage:
  warden agent switch [AGENT] [flags]


Flags:
      --aicli string    explicit successor AI CLI id (claude, antigravity, codex, …)
  -h, --help            help for switch
      --json            emit result as JSON
  -m, --model string    explicit successor model id (requires --aicli)
  -p, --prompt string   optional extra instruction appended to successor's continuation prompt
      --reason string   reason recorded for hot-swap (manual|context_fill|quota) (default "manual")
  -r, --role string     role whose tier to resolve the successor from when --tier is not given; does NOT change the agent's role (use 'warden agent set <AGENT> role <ROLE>')
  -t, --tier string     resolve successor via quota-balanced router at this tier (tier-1|tier-2|tier-3)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent set

Section titled “warden agent set”
Change one per-agent setting. Each key runs the same code path as its older command.


Keys and values:
  permission-mode  acceptEdits | auto | bypassPermissions | default | dontAsk | plan
  permission-posture read-only | read-write | allowlisted | dangerously-execute-all
  compact          on | off | inherit
  role             general | autopilot | brain | orchestrator | planner | worker
  auto-approve     on | off


Warnings:
  role          RELAUNCHES the agent so the new persona is injected; its current
                turn is discarded.
  compact on    force-compact can INTERRUPT an in-flight turn (Escape, /compact,
                then resume) when the context crosses the critical threshold.


Examples:
  warden agent set abc123 permission-mode acceptEdits
  warden agent set abc123 permission-posture dangerously-execute-all
  warden agent set abc123 compact inherit
  warden agent set abc123 role reviewer
  warden agent set abc123 auto-approve on


See also: 'warden agent get <AGENT> [key]' to read the current values.


Usage:
  warden agent set <AGENT> <key> <value> [flags]


Flags:
  -h, --help   help for set


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent get

Section titled “warden agent get”
Show the current value of one or all per-agent settings, read from the agent's
status record.


Keys: permission-mode, permission-posture, compact, role, auto-approve


An empty permission-mode means no per-agent override (the global default applies);
compact "inherit" means the global token_force_compact setting applies; role
"general" means no persona.


Examples:
  warden agent get abc123
  warden agent get abc123 role
  warden agent get abc123 --json


Usage:
  warden agent get <AGENT> [key] [flags]


Flags:
  -h, --help   help for get
      --json   emit settings as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent role

Section titled “warden agent role”
Inspect warden's built-in agent roles and tier mappings


Usage:
  warden agent role [flags]


Commands:
  list                 List the built-in agent roles and their descriptions
  tier                 Inspect and manage role-to-tier mappings


Flags:
  -h, --help   help for role


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent role list

Section titled “warden agent role list”
List the built-in agent roles and their descriptions


Usage:
  warden agent role list [flags]


Flags:
  -h, --help   help for list
      --json   emit the roles as a JSON array


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent role tier

Section titled “warden agent role tier”
Inspect and manage default model tier mappings for agent roles.


Subcommands:
  list    List all role-to-tier mappings
  set     Set the default model tier for a role


When run without subcommands, `warden agent role tier` lists all mappings.


Usage:
  warden agent role tier [flags]


Commands:
  list                 List agent roles and their default model tiers
  set                  Set the default model tier for an agent role (tier-1|tier-2|tier-3)


Flags:
  -h, --help   help for tier
      --json   emit role tier mappings as a JSON array


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden agent role tier list

Section titled “warden agent role tier list”
List agent roles and their default model tiers


Usage:
  warden agent role tier list [flags]


Flags:
  -h, --help   help for list
      --json   emit role tier mappings as a JSON array


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden agent role tier set

Section titled “warden agent role tier set”
Set the default model tier assigned when creating agents with this role.


Tiers:
  tier-1   Highest-capability models (e.g. Claude Opus, o1) for architecture, design, and complex planning
  tier-2   Standard implementation models (e.g. Claude Sonnet, Gemini Pro, GPT-4.1) for everyday coding
  tier-3   Fast, low-cost models (e.g. Claude Haiku, Gemini Flash, GPT-4.1-mini) for quick tasks and CI triage


Example:
  warden agent role tier set worker tier-2
  warden agent role tier set orchestrator tier-1


Usage:
  warden agent role tier set <role> <tier> [flags]


Flags:
  -h, --help   help for set


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline

Section titled “warden pipeline”
Define and run a DAG of dependent agent jobs.


Typical journey:
  1. Write a YAML spec, or pick a starter with `wd pipeline template list`
  2. `wd pipeline validate <spec.yaml>` — check the DAG locally (no daemon)
  3. `wd pipeline create <spec.yaml>` — register it (or add --start to begin immediately)
  4. `wd pipeline start <id>` — spawn jobs that have no dependencies
  5. `wd pipeline show <id> --watch` — follow progress until it finishes
  6. On failure, `wd pipeline job retry <id> <job>` to re-run a failed job


pause stops new jobs from spawning while in-flight agents finish (undo with resume).
cancel terminates running job agents and cannot be undone — create a new pipeline to run again.
delete removes the pipeline record after jobs are settled (cancel first if any are live).


Examples:
  wd pipeline template list
  wd pipeline validate review.yaml
  wd pipeline create review.yaml --start
  wd pipeline show my-run --watch


Usage:
  warden pipeline [flags]


Commands:
  validate             Validate a pipeline YAML spec without creating it
  create               Create a pipeline from a YAML spec or a built-in template
  template             Built-in pipeline templates
  list                 List pipelines
  show                 Show a pipeline's jobs and their status
  start                Start a pipeline (spawns jobs with no dependencies)
  pause                Pause a running pipeline (in-flight jobs finish; no new jobs spawn)
  resume               Resume a paused pipeline (spawns jobs that became ready while paused)
  cancel               Cancel a pipeline (terminates running jobs)
  delete               Delete a pipeline's record (must not have live jobs — cancel first)
  emit                 Publish this job's handoff (run from inside a pipeline job)
  job                  Inspect, edit and retry one job of a pipeline


Flags:
  -h, --help   help for pipeline


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline validate

Section titled “warden pipeline validate”
Parse and validate a pipeline spec locally — checks required fields, job ids, dependency references, worktree/run_if values, and DAG cycles. Exits 0 if valid, 1 if not (suitable for CI). Does not contact the daemon.


Pass the spec as a positional argument or with -f (not both).


Examples:
  wd pipeline validate review.yaml
  wd pipeline validate -f review.yaml


Usage:
  warden pipeline validate [spec.yaml] [flags]


Flags:
  -f, --file string   path to the pipeline YAML spec
  -h, --help          help for validate


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline create

Section titled “warden pipeline create”
Create a pipeline either from a YAML spec file (positional or -f) or from a
built-in template (--template). Templates render with placeholder substitution:
--name fills {{NAME}} (default the template name), --repo fills {{REPO}}
(default the current directory), and each remaining {{KEY}} is filled with
--set KEY=VALUE. Run `wd pipeline template list` to see templates and their
placeholders.


--start begins the pipeline right after creating it. --json prints the created
pipeline as JSON.


Examples:
  wd pipeline create review.yaml
  wd pipeline create review.yaml --start
  wd pipeline create --template analyze-implement-review --set TASK="add a flag" --start
  wd pipeline create -f review.yaml --json


Usage:
  warden pipeline create [spec.yaml] [flags]


Flags:
  -f, --file string       path to the pipeline YAML spec
  -h, --help              help for create
      --json              print the created pipeline as JSON
      --name string       pipeline name — fills {{NAME}} (default: the template name)
      --plan string       optional plan id to link for reference; does not make that plan run this pipeline
      --project string    optional project id this pipeline joins; overrides YAML project_id (default: git root of --repo / the spec file / cwd, unless the YAML sets project_id)
      --repo string       repo path — fills {{REPO}} (default: the current directory)
      --set stringArray   fill a template placeholder, KEY=VALUE (repeatable)
      --start             start the pipeline immediately after creating it
      --template <NAME>   built-in template <NAME> to render (see 'wd pipeline template list')


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline template

Section titled “warden pipeline template”
Built-in pipeline templates render via create --template and support placeholder
substitution. `template list` names them; `template show` prints one template's
YAML. The pipeline templates section of `wd project library list` shows the same
catalog alongside spawn presets and prompt templates.


Usage:
  warden pipeline template [flags]


Commands:
  list                 List the built-in pipeline templates and their placeholders
  show                 Print a built-in pipeline template's YAML


Flags:
  -h, --help   help for template


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline template list

Section titled “warden pipeline template list”
List the built-in pipeline templates bundled with warden, each with a short
description and the placeholders create --template needs. The same catalog
appears under PIPELINE TEMPLATES in `wd project library list`.


Examples:
  wd pipeline template list


Usage:
  warden pipeline template list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline template show

Section titled “warden pipeline template show”
Print the raw YAML of a built-in pipeline template, including its leading
description comment and {{PLACEHOLDER}} markers. Use create --template to
render and register one.


Examples:
  wd pipeline template show analyze-implement-review


Usage:
  warden pipeline template show <name> [flags]


Flags:
  -h, --help   help for show


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline list

Section titled “warden pipeline list”
List pipelines as a table. By default only the project of the current
directory is listed; use --all for every project or --project to pick one.
Outside any project all pipelines are listed.


Columns: NAME, STATUS, JOBS (finished/total of the jobs in the spec),
PROJECT (only with --all), PLAN (the plan it executes, or -) and
SCHEDULE (only when a pipeline was started by a schedule).


Usage:
  warden pipeline list [flags]


Examples:
  warden pipeline list
    warden pipeline list --all --status running,paused
    warden pipeline list --project ~/dev/app --json


Flags:
      --all                    list pipelines from every project
  -h, --help                   help for list
      --json                   output as JSON
      --project <id-or-path>   project <id-or-path> (default: the project of the current directory)
      --status strings         only pipelines in this status (repeatable or comma-separated: pending, running, paused, done, stalled, canceled)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden pipeline show

Section titled “warden pipeline show”
Show a pipeline: a header (name, status, project, repo, and the plan and
schedule it belongs to) followed by a table of its jobs with status, agent,
backend and model, what each job waits on, and its branch. A job that needs
attention is marked with "!". A job's output appears as one truncated line
beneath it; --json carries the full text.


Jobs warden adds on its own to fan work out and join it back are hidden by
default; pass --all-jobs to list them too, marked [warden].


--prompts also prints each job's prompt and handoff hint. --watch refreshes
the view every few seconds until the pipeline is done, stalled or canceled, or
you interrupt it. A pipeline that belongs to a plan points you at
`wd plan show <plan-id>`.


Examples:
  wd pipeline show my-run
  wd pipeline show my-run --prompts
  wd pipeline show my-run --watch
  wd pipeline show my-run --json | jq '.jobs[].status'


Usage:
  warden pipeline show <pipeline> [flags]


Flags:
      --all-jobs   also list jobs warden added itself (marked [warden])
  -h, --help       help for show
      --json       output as JSON
      --prompts    print each job's prompt and handoff hint
      --watch      refresh the view every few seconds until the pipeline finishes or you interrupt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline start

Section titled “warden pipeline start”
Start a pending pipeline: spawns its jobs that have no dependencies;
dependents spawn automatically as their upstreams emit. Refuses if the
pipeline was already started. A canceled pipeline cannot be restarted —
create a new one from the same spec or template.


Examples:
  wd pipeline start my-run


Usage:
  warden pipeline start <pipeline> [flags]


Flags:
  -h, --help   help for start


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline pause

Section titled “warden pipeline pause”
Pause a running pipeline: jobs that are already running keep going, but no
new jobs spawn until you resume. Undo with `wd pipeline resume`. Only a
running pipeline can be paused.


Examples:
  wd pipeline pause my-run


Usage:
  warden pipeline pause <pipeline> [flags]


Flags:
  -h, --help   help for pause


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline resume

Section titled “warden pipeline resume”
Resume a paused pipeline: spawns any jobs that became ready while it was
paused and continues the DAG. Only a paused pipeline can be resumed.


Examples:
  wd pipeline resume my-run


Usage:
  warden pipeline resume <pipeline> [flags]


Flags:
  -h, --help   help for resume


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline cancel

Section titled “warden pipeline cancel”
Cancel a pipeline: terminates any live job agents and marks remaining jobs
skipped. A canceled pipeline cannot be restarted — create a new one from the
same spec or template if you need to run it again.


When jobs are still running, asks for confirmation (skip with --yes). With no
running jobs it cancels without asking. Non-interactive sessions must pass --yes
when jobs are running.


Examples:
  wd pipeline cancel my-run
  wd pipeline cancel my-run --yes


Usage:
  warden pipeline cancel <pipeline> [flags]


Flags:
  -h, --help   help for cancel
  -y, --yes    skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline delete

Section titled “warden pipeline delete”
Delete a pipeline record and its job history. Agent sessions for settled jobs
are archived; branches and worktrees are left in place. Refuses while any job is
still live — cancel first.


Asks for confirmation unless --yes is given. Non-interactive sessions must pass
--yes.


Examples:
  wd pipeline delete my-run
  wd pipeline delete my-run --yes


Usage:
  warden pipeline delete <pipeline> [flags]


Flags:
  -h, --help   help for delete
  -y, --yes    skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline emit

Section titled “warden pipeline emit”
Publish this job's handoff text so dependent jobs can start. Intended to be
called by the job's own agent (pipeline and job ids come from
$WARDEN_PIPELINE_ID and $WARDEN_JOB_ID). Called elsewhere, you must pass
--pipeline and --job; emitting for the wrong job or after the job has
already emitted is refused.


Examples:
  wd pipeline emit "plan ready; start with auth.go"
  wd pipeline emit --pipeline my-run --job analyze "done"


Usage:
  warden pipeline emit <text> [flags]


Flags:
  -h, --help              help for emit
      --job string        job id (defaults to $WARDEN_JOB_ID)
      --pipeline string   pipeline id (defaults to $WARDEN_PIPELINE_ID)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline job

Section titled “warden pipeline job”
Commands that act on a single job of a pipeline: show everything about it, edit a job that has not started, or retry one that failed.


Usage:
  warden pipeline job [flags]


Commands:
  show                 Show everything about one job
  edit                 Edit the prompt and/or handoff of a job that has not started
  retry                Re-run a failed or needs-attention job (reopens skipped descendants)


Flags:
  -h, --help   help for job


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline job show

Section titled “warden pipeline job show”
Show one job of a pipeline in full: its status, type, role, tier, backend and
model, worktree mode, whether it is supervised, when it runs, what it depends
on, the agent and session that ran it, its branch, how many times it was
retried automatically, and its complete prompt, handoff hint and output.


Jobs warden adds on its own to fan work out and join it back are shown too,
marked as created by warden. --json prints the job as JSON.


Examples:
  wd pipeline job show my-run build
  wd pipeline job show my-run build --json


Usage:
  warden pipeline job show <pipeline> <job> [flags]


Flags:
  -h, --help   help for show
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline job edit

Section titled “warden pipeline job edit”
Change the prompt and/or handoff hint of a job before it starts. A job that
has already started cannot be edited.


Examples:
  wd pipeline job edit my-run build --prompt "build with -race"
  wd pipeline job edit my-run build --handoff "report the test count"


Usage:
  warden pipeline job edit <pipeline> <job> [flags]


Flags:
      --handoff string   new handoff hint for the job
  -h, --help             help for edit
      --prompt string    new prompt for the job


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden pipeline job retry

Section titled “warden pipeline job retry”
Re-run a job that failed or needs attention. Jobs downstream of it that were
skipped because it failed are reopened so the pipeline can carry on.


Example:
  wd pipeline job retry my-run build


Usage:
  warden pipeline job retry <pipeline> <job> [flags]


Flags:
  -h, --help   help for retry


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan

Section titled “warden plan”
Manage plans tracked by the daemon.


Plans are canonical ScrivaDB records (goal, tasks, lifecycle, revision).
Repository YAML under plans/ is an optional inert export — not required
for create/run/complete/archive.


Typical journey:


  1. Create    `wd plan create` (then `wd plan show` to inspect it)
  2. Edit      `wd plan update`, `wd plan edit` or `wd plan task add|edit|rm`
               (only while the plan is pending)
  3. Run       `wd plan run --mode <mode>` (pending → in_progress); follow
               progress with `wd plan show --watch`
  4. Control   `wd plan pause`, `resume` or `stop` the running executor
  5. Progress  `wd plan task status` / `wd plan done` record task progress
  6. Complete  `wd plan complete` (in_progress → completed). An autopilot plan
               does this itself: the daemon opens one final PR to the
               default branch and gets it green, the plan waits for you
               to merge it, then completes and deletes the integration
               branch by itself
  7. Finish    `wd plan archive` (reversible with `wd plan unarchive`), or
               `wd plan delete` to remove a pending or archived plan permanently
  8. Ship      `wd workspace clean` removes leftover merged branches;
               `wd release` tags the next release


Usage:
  warden plan [flags]


Commands:
  list                 List plans for a project
  create               Create a canonical plan in ScrivaDB
  update               Update a pending plan definition
  edit                 Edit a pending plan definition in $EDITOR
  task                 Add, edit, or remove tasks on a pending plan
  show                 Show detail for one plan
  related              List heuristic related / overlapping plans
  run                  Start execution of a plan in the given mode
  pause                Pause an in-progress plan's executor
  resume               Resume a paused plan's executor
  stop                 Stop an in-progress plan's executor
  restart              Restart an in-progress plan's executor with fresh agents
  done                 Mark a plan task done
  complete             Complete a plan (in_progress → completed)
  archive              Archive a plan (reversible with `plan unarchive`)
  unarchive            Restore an archived plan to the status it was archived from
  delete               Permanently delete a plan
  sync-to-repo         Export a plan revision to a dedicated branch and open a PR
  hub-sync             Explicitly sync canonical plans with the configured Hub
  backup               Export or restore a portable Plan backup bundle
  import-legacy        Import legacy plans/**/*.yaml into ScrivaDB (operator cutover)
  assess               Brain-assisted task progress assessment


Flags:
  -h, --help   help for plan


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan list

Section titled “warden plan list”
List plans registered in the daemon for a project.


Use --project to specify the project (defaults to the git root of the current directory).
Filter by lifecycle stage with --status.


Usage:
  warden plan list [flags]


Flags:
  -h, --help             help for list
      --json             output as JSON
      --project string   project ID (default: git root of the current directory)
      --status string    filter by status: pending|in_progress|completed|archived


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden plan create

Section titled “warden plan create”
Create a new pending plan in the daemon's ScrivaDB store (no repository
YAML write). --name and --goal are required. Supply tasks with repeatable
--task flags, or (when stdin is a TTY) enter them interactively.


Plans are task DAGs: edges are after-deps. Prefer
--task id@dep1,dep2:prompt. If you pass two or more tasks with no after
edges, warden chains them in flag order so every multi-task plan has a DAG.


Optional --constraint and --done-when may be repeated.


Usage:
  warden plan create --name <name> --goal <text> [flags]


Flags:
      --constraint stringArray   constraint the workers must follow (repeatable)
      --done-when stringArray    completion criterion (repeatable)
      --goal string              what the plan is trying to achieve
  -h, --help                     help for create
      --json                     output as JSON
      --name string              plan name
      --project string           project ID (default: git root of the current directory)
      --task stringArray         task as id:prompt or id@dep1,dep2:prompt (repeatable; skip interactive prompt)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan update

Section titled “warden plan update”
Change a pending plan's definition. Only pending plans can be edited;
once a plan is running, completed or archived the update is refused.


Provide at least one of --file, --name, --goal, --constraint, or --done-when.
When --file is set, the plan YAML in that file is applied first and any
explicit flags overlay those fields. The update is checked against the
plan's current revision, so it fails if the plan changed since it was read.


Usage:
  warden plan update <plan-id> [flags]


Flags:
      --constraint stringArray   replace constraints (repeatable)
      --done-when stringArray    replace done_when criteria (repeatable)
      --file string              YAML definition file to apply
      --goal string              new plan goal
  -h, --help                     help for update
      --json                     output as JSON
      --name string              new plan name


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan edit

Section titled “warden plan edit”
Fetch a pending plan's definition, open it as YAML in $EDITOR (or $VISUAL,
falling back to vi), then apply the saved document as the new definition.


Only name, goal, constraints, done_when, and tasks are written/applied.
Lifecycle and execution fields are ignored. If the editor exits non-zero or
the file is unchanged, no API call is made. Optimistic concurrency uses the
revision observed at fetch time.


Usage:
  warden plan edit <plan-id> [flags]


Flags:
  -h, --help   help for edit
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan task

Section titled “warden plan task”
Manage a plan's tasks. add, edit and rm change the task definitions and only
work on pending plans; status records progress and is used while a plan runs.


  add     Append a task to the plan
  edit    Change one task's prompt or dependencies
  rm      Remove a task (refused while other tasks depend on it)
  status  Set a task's status (pending|in_progress|done|skipped)


edit and rm take the task id as the second argument (or --id). The skipped
status counts as finished: `plan complete` accepts done or skipped tasks.


Usage:
  warden plan task [flags]


Commands:
  add                  Add a task to a pending plan
  edit                 Edit a task definition on a pending plan
  rm                   Remove a task from a pending plan
  status               Set a plan task's status


Flags:
  -h, --help   help for task


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan task add

Section titled “warden plan task add”
Append a task to a pending plan's DAG. --id and --prompt are required.
Repeat --after for dependencies. Optional --expected-revision fails the change
if the plan was modified since that revision (omit to skip the check).


Usage:
  warden plan task add <plan-id> [flags]


Flags:
      --after stringArray       dependency task id (repeatable)
      --expected-revision int   fail if the plan is no longer at this revision (omit to skip the check)
  -h, --help                    help for add
      --id string               task id
      --json                    output as JSON
      --prompt string           task prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan task edit

Section titled “warden plan task edit”
Patch one task's prompt and/or after-deps on a pending plan. Pass the task
id as a second argument or via --id. Provide --prompt and/or --after; omitted fields are left unchanged.
Optional --expected-revision fails the change if the plan was modified
since that revision (omit to skip the check).


Usage:
  warden plan task edit <plan-id> [task-id] [flags]


Flags:
      --after stringArray       replace after-deps (repeatable; pass once with empty to clear)
      --expected-revision int   fail if the plan is no longer at this revision (omit to skip the check)
  -h, --help                    help for edit
      --id string               task id (alternative to positional)
      --json                    output as JSON
      --prompt string           new task prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan task rm

Section titled “warden plan task rm”
Remove a task from a pending plan. Pass the task id as a second argument
or via --id. Removal is rejected if other tasks still depend on it.
Optional --expected-revision fails the change if the plan was modified
since that revision (omit to skip the check).


Usage:
  warden plan task rm <plan-id> [task-id] [flags]


Flags:
      --expected-revision int   fail if the plan is no longer at this revision (omit to skip the check)
  -h, --help                    help for rm
      --id string               task id (alternative to positional)
      --json                    output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan task status

Section titled “warden plan task status”
Set one task's progress status to pending, in_progress, done, or skipped.
Prints the task's old and new status plus the plan's task summary. Works on
plans in any lifecycle state. skipped counts as finished for `plan complete`.
`wd plan done <plan-id> <task-id>` is the shorthand for setting a task to done.


Usage:
  warden plan task status <plan-id> <task-id> <pending|in_progress|done|skipped> [flags]


Flags:
  -h, --help   help for status
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan show

Section titled “warden plan show”
Show the full canonical ScrivaDB record for one plan: goal, tasks, status,
revision, executor, task summary, export status, linked branches, and timestamps.
Repository YAML is never read for this view.


For an in_progress plan it is the single status view of the run: executor
kind and state (active, healing, degraded, paused, stopped), backoff detail
when present, the integration branch, and per task the state, worker agent
and PR, plus the final PR (integration → default branch) once it exists. Use
--watch to keep refreshing it.


For a completed plan it prints an outcome block: the final PR and its state,
the integration branch and what became of it (deleted, kept, abandoned,
delete failed), the execution summary (duration, tasks done and skipped, PRs
landed) and any recorded cleanup failures. A plan completed before this
record existed whose integration branch still has commits not on the default
branch gets a warning line naming the branch (`plan list --json` flags it as
integration_branch_leftover).


Usage:
  warden plan show <plan-id> [flags]


Flags:
  -h, --help    help for show
      --json    output as JSON
      --watch   refresh the view every few seconds until interrupted


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)
Section titled “warden plan related”
List related plans for a canonical ScrivaDB plan using heuristic overlap
on project, title, goal, and linked branches/PRs.


Hits are discovery aids only — not authoritative identity or duplicate detection.
Repository YAML replicas never appear as additional plans.


Usage:
  warden plan related <plan-id> [flags]


Flags:
  -h, --help        help for related
      --json        output as JSON
      --limit int   maximum hits to return (default 10)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan run

Section titled “warden plan run”
Start execution of a plan (pending → in_progress). This is the only supported
public start path for plan execution (including autopilot). --mode is
required; it decides how the plan is executed:


  autopilot            Creates a live Autopilot executor + manager
                       (pause/resume supported)
  pipeline             Each task becomes a pipeline job
                       (pause/resume supported)
  orchestrator_worker  Orchestrator + workers with human approval gates
                       (pause/resume refused; use stop)
  manual               Plan-bound general agent; human drives prompting
                       (pause/resume refused; use stop)


`orchestrator` is accepted as a shorthand for `orchestrator_worker`.
An autopilot run ends with one final PR to the default branch; you merge it.
Follow progress with `wd plan show --watch`. `wd plan stop` works for every
mode; `wd plan pause|resume` only for autopilot and pipeline.


Usage:
  warden plan run <plan-id> [flags]


Flags:
  -h, --help          help for run
      --json          output as JSON
      --mode string   execution mode (required): autopilot|pipeline|orchestrator_worker|manual


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan pause

Section titled “warden plan pause”
Pause the executor of an in-progress plan so no new work starts. The plan
stays in_progress; undo with `wd plan resume`.


  autopilot     The run is paused. Workers already running keep going.
  pipeline      No new jobs are started. Jobs already running keep going
                and may still finish or fail.
  plan-bound    Not supported (orchestrator and manual plans); use
  agent         `wd plan stop` instead.


Only plans that are in_progress and have an active executor can be controlled.




Usage:
  warden plan pause <plan-id> [flags]


Flags:
  -h, --help   help for pause
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan resume

Section titled “warden plan resume”
Resume an executor paused with `wd plan pause`. The plan stays in_progress.


  autopilot     The paused run becomes active again (its brain is respawned
                if it was torn down).
  pipeline      Jobs that became ready while paused are started.
  plan-bound    Not supported (orchestrator and manual plans).
  agent


Resuming an executor that is not paused is refused. A stopped executor
cannot be resumed — use `wd plan restart` to bring it back.


Only plans that are in_progress and have an active executor can be controlled.




Usage:
  warden plan resume <plan-id> [flags]


Flags:
  -h, --help   help for resume
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan stop

Section titled “warden plan stop”
Stop the executor of an in-progress plan. The plan itself stays in_progress
(stop does not complete, archive or reset it).


  autopilot     The run is stopped and its brain is shut down. A stopped
                run cannot be resumed; use `wd plan restart`.
  pipeline      The pipeline is canceled: running jobs are terminated and
                unfinished jobs are skipped. It cannot be resumed; use
                `wd plan restart`.
  plan-bound    The agent is terminated.
  agent


A stopped plan is not re-run with `wd plan run` (that needs a pending plan).
Record the outcome with `wd plan task status`, then `wd plan complete`, or
`wd plan archive` to give up.


Only plans that are in_progress and have an active executor can be controlled.




Usage:
  warden plan stop <plan-id> [flags]


Flags:
  -h, --help   help for stop
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan restart

Section titled “warden plan restart”
Restart the executor of an in-progress plan with a brand-new set of agents,
keeping the work already done. Use it when a plan is stopped, degraded,
parked or stuck. This is destructive: the old agents are terminated and
their worktrees removed.


  autopilot     The manager and workers are terminated and their worktrees
                removed. The landed-task ledger and the plan's tasks are kept;
                branches with unmerged commits are kept, empty ones deleted.
                A new manager starts with a restart context (what is merged,
                what is unfinished); in-flight tasks are re-issued.
  pipeline      Running job agents are terminated and their worktrees removed.
                Done jobs and handoffs are kept; failed, skipped and unfinished
                jobs are reset and re-run with fresh agents. Branches with
                commits are kept as the base for the re-run.
  orchestrator_worker, manual
                Not supported; use `wd plan stop` and run a new path.


An executor that is still active, starting or paused is refused unless
--force is given. --backend picks the backend of the new autopilot manager.
Without --yes the command asks for confirmation and refuses when stdin is
not a terminal.


Usage:
  warden plan restart <plan-id> [flags]


Flags:
      --backend string   backend id for the new autopilot manager (autopilot only)
      --force            restart even when the executor is active, starting or paused
  -h, --help             help for restart
      --json             output as JSON
  -y, --yes              skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan done

Section titled “warden plan done”
Shorthand for `plan task status <plan-id> <task-id> done`. Updates the
task's progress on the plan.


Usage:
  warden plan done <plan-id> <task-id> [flags]


Flags:
  -h, --help   help for done
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan complete

Section titled “warden plan complete”
Complete a plan: in_progress → completed. An autopilot plan runs this
automatically once its final PR is merged; run it by hand for other modes,
or to finish an autopilot plan without waiting for the merge. Blocked if any task is not
done or skipped (skipped counts as finished), or if any branch the plan's
work opened a PR for is still unmerged.


For an autopilot plan whose integration branch still has commits not on
the default branch and no matching merged final PR, completion is refused
unless --abandon-unmerged is set (keeps the branch; records it as abandoned).


On success the daemon records an execution summary on the plan, tears down
its executor (autopilot run, pipeline and plan-bound agents), and removes
their worktrees and branches. The plan record itself is kept; PR references
and execution history are preserved. If cleanup only partly succeeds the
plan stays in_progress and the command can be run again.


The plan keeps an outcome record — final PR, integration branch and whether
it was deleted — that `wd plan show` prints for completed plans.


Usage:
  warden plan complete <plan-id> [flags]


Flags:
      --abandon-unmerged   complete even when the integration branch has unmerged commits; keep the branch
  -h, --help               help for complete
      --json               output as JSON
      --yes                skip the abandon-unmerged confirmation


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan archive

Section titled “warden plan archive”
Move a plan to the archived state, recording the status it was archived from
so `wd plan unarchive` can restore it.


Pending and completed plans archive as a status change only. An in-progress
plan whose executor is still live (starting, active, paused, healing,
degraded, finalizing or awaiting final PR merge) is refused: run
`wd plan stop <plan-id>` first. With the executor stopped or absent, archive
tears down what the run left behind — the executor record, plan-bound agents
and their worktrees — and reports what was removed.


Never torn down: any branch (worker or integration) with commits that are not
on the default branch is kept, locally and on origin, and listed in the
output. Open PRs are left open. Task progress and the plan record are kept.


Usage:
  warden plan archive <plan-id> [flags]


Flags:
  -h, --help   help for archive
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan unarchive

Section titled “warden plan unarchive”
Return an archived plan to the status it was archived from (pending,
in_progress or completed) and clear its archived marker. A plan archived
before that status was recorded returns to completed when it has a completion
time, otherwise to pending (task progress is kept).


An in-progress plan comes back in_progress with a stopped executor; nothing is
started. Run `wd plan restart <plan-id>` to continue it. Refused on a plan
that is not archived.


Usage:
  warden plan unarchive <plan-id> [flags]


Flags:
  -h, --help   help for unarchive
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan delete

Section titled “warden plan delete”
Permanently delete a pending or archived plan. This cannot be undone; use
`plan archive` for the reversible alternative. Consider `plan backup export`
first. In-progress plans (stop and archive first) and completed plans (archive
first) are refused. Any YAML replica in the repository is left untouched.
Asks for confirmation unless --yes is given; --json requires --yes.


Usage:
  warden plan delete <plan-id> [flags]


Flags:
  -h, --help   help for delete
      --json   output as JSON (requires --yes)
  -y, --yes    skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan sync-to-repo

Section titled “warden plan sync-to-repo”
Render the canonical ScrivaDB Plan as an inert replica (YAML by default;
`--format json` for JSON) on a dedicated `warden/plan-sync/<plan-id>/<revision>`
branch and open (or reuse) a PR against --base. Uses an isolated git worktree —
never stages the operator's checked-out branch, force-pushes, auto-merges, or
overwrites a conflicting non-Warden file. Repeating the same revision/hash for
the same repo/ref/path returns the prior result with no new GitHub activity.


Usage:
  warden plan sync-to-repo <plan-id> [flags]


Flags:
      --base string         PR base branch / target ref (required)
      --format string       replica format: yaml (default) or json (default "yaml")
  -h, --help                help for sync-to-repo
      --json                output as JSON
      --path string         replica output path override (default: plans/{lifecycle}/<slug>.{yaml|json})
      --repo string         local git repository path (default: plan project root)
      --repository string   stable repository identity for export records (default: origin URL)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan hub-sync

Section titled “warden plan hub-sync”
Explicit, operator-driven sync of canonical plans with the configured Hub.
Nothing syncs automatically: the Hub is only contacted when you run one of
these subcommands.


  discover  List plans the Hub offers (read-only)
  pull      Fetch plan envelopes from the Hub (does not overwrite local plans)
  push      Offer one local plan revision to the Hub


Usage:
  warden plan hub-sync [flags]


Commands:
  discover             List plans available on the Hub
  pull                 Fetch plan envelopes from the Hub
  push                 Push one local plan revision to the Hub


Flags:
  -h, --help   help for hub-sync


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan hub-sync discover

Section titled “warden plan hub-sync discover”
Ask the Hub which plans it has in scope and print their envelopes. This is
read-only discovery: nothing is imported. With a plan id, the result is
limited to that plan (narrow further with --status).


Usage:
  warden plan hub-sync discover [plan-id] [flags]


Flags:
  -h, --help                 help for discover
      --json                 output as JSON
      --scope string         Hub project scope to search (default: unscoped)
      --status stringArray   lifecycle status filter (repeatable)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan hub-sync pull

Section titled “warden plan hub-sync pull”
Fetch plan envelopes from the Hub and print them. Pulling never imports or
overwrites local plan definitions; it only stamps sync metadata on local
plans the Hub already knows. With a plan id, only that plan is fetched;
otherwise all plans in scope are returned (narrow with --status).


Usage:
  warden plan hub-sync pull [plan-id] [flags]


Flags:
  -h, --help                 help for pull
      --json                 output as JSON
      --scope string         Hub project scope to pull from (default: unscoped)
      --status stringArray   lifecycle status filter (repeatable)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan hub-sync push

Section titled “warden plan hub-sync push”
Send a local plan's current revision to the Hub and stamp the local record
with the remote id and sync time. The plan id is required.


Usage:
  warden plan hub-sync push <plan-id> [flags]


Flags:
  -h, --help                 help for push
      --json                 output as JSON
      --scope string         Hub project scope to push into (default: the plan's own project)
      --status stringArray   lifecycle status filter (repeatable)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan backup

Section titled “warden plan backup”
Local backup / machine-transfer for canonical ScrivaDB Plans.


Bundles include definition, revision, execution evidence, events/notes,
and integrity hashes. They exclude credentials and disposable worktrees.
Restore never consults Git or repository replicas under plans/.


Usage:
  warden plan backup [flags]


Commands:
  export               Write a Plan backup bundle to a file or stdout
  restore              Restore Plans from a backup bundle into ScrivaDB


Flags:
  -h, --help   help for backup


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan backup export

Section titled “warden plan backup export”
Export one or more Plans from ScrivaDB into a versioned backup bundle.
Pass plan IDs as args, or --all (optionally scoped with --project).


  wd plan backup export plan-ab12cd34 -o plan.bundle.json
  wd plan backup export --all --project /path/to/repo -o all-plans.json


Usage:
  warden plan backup export [plan-id ...] [flags]


Flags:
      --all              export every plan (optionally scoped by --project)
  -h, --help             help for export
      --json             with -o, print the export summary as JSON instead of text (the bundle itself is always JSON)
  -o, --output string    output file (default: stdout)
      --project string   when used with --all, limit export to this project id


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan backup restore

Section titled “warden plan backup restore”
Validate and restore a Plan backup bundle. Does not read Git or plans/
replicas. Re-running the same bundle is idempotent when identity +
content hash + revision match.


  wd plan backup restore plan.bundle.json --dry-run
  wd plan backup restore plan.bundle.json --on-conflict skip


Usage:
  warden plan backup restore <bundle-file> [flags]


Flags:
      --dry-run              validate integrity and conflicts without writing
  -h, --help                 help for restore
      --json                 output as JSON
      --on-conflict string   stable-id policy: skip|fail|overwrite (default "skip")


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan import-legacy

Section titled “warden plan import-legacy”
Discover plans/{pending,in_progress,completed,archived}/*.yaml (and flat
plans/*.yaml) and create or reconcile canonical ScrivaDB Plans by stable
identity. Source files are left untouched.


Repeated import with a matching content hash is a no-op (skipped). An
existing canonical definition with a different hash is reported as
conflicted without mutation.


--report classifies without writing. Never runs automatically at daemon
startup.


Usage:
  warden plan import-legacy [flags]


Flags:
  -h, --help             help for import-legacy
      --json             output as JSON
      --project string   project ID (default: git root of the current directory)
      --report           classify without mutating ScrivaDB


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden plan assess

Section titled “warden plan assess”
Use a brain model to reconstruct task progress from git history and open PRs.
Updates the plan's recorded task progress. Opt-in — never run automatically.
Plan ids resolve globally; --project is optional and rarely needed.


Usage:
  warden plan assess <plan-id> [flags]


Flags:
  -h, --help   help for assess
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden autopilot

Section titled “warden autopilot”
Autopilot is the unattended Plan execution mode. There is no per-repo switch:
start a run explicitly with `warden plan run <plan-id> --mode autopilot` and
control it with `warden plan pause|resume|stop`. This namespace shows status
(`status`) and lands worker branches (`land`).
The daemon merges worker PRs into the integration branch itself once their
gate is green; `land` is the manual fallback. A run ends with one final PR to
the default branch that you merge.
Configure the feature under the `autopilot` block in the config file.


Usage:
  warden autopilot [flags]


Commands:
  status               List every autopilot run
  land                 Land an autopilot worker branch into the integration branch


Flags:
  -h, --help   help for autopilot


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden autopilot status

Section titled “warden autopilot status”
The all-runs view: one table row per autopilot run (run id, name, state, plan,
gate, branch and task progress; the repo column appears only when runs span
more than one repo). Runs that are waiting, degraded or need attention print
indented detail lines under their row (supervisor, next step, resting until, the
daemon supervisor's diagnosis, the final PR). Use `wd plan show <id> --watch` for the view of one
plan. --json emits the raw result.


Usage:
  warden autopilot status [flags]


Flags:
  -h, --help   help for status
      --json   emit the raw autopilot status as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden autopilot land

Section titled “warden autopilot land”
Merges one autopilot worker branch into the integration branch. The daemon
does this itself when a worker PR's gate is green; `land` is the manual
fallback for an operator or manager, with the same preconditions.


It checks that the owning run is active, the branch is autopilot-owned, a PR
targets the integration branch, the gate is green for the PR head, and the PR
is mergeable. It then merges with the configured strategy, deletes the worker
branch if configured, and records the landing. Re-running after a merge
reports already-landed without merging again.


If a check fails, nothing is merged and one error names the reason:


  not_found      no agent or branch matches the name
  not_owned      the branch exists but no autopilot run owns it
  run_disabled   the run is paused or stopped
  wrong_base     the PR does not target the integration branch
  gate_pending   the gate has not finished yet
  gate_red       the gate failed
  ci_missing     the gate needs CI but the PR has none
  not_mergeable  the PR has conflicts


Usage:
  warden autopilot land <agent-or-branch> [flags]


Flags:
  -h, --help   help for land
      --json   emit the raw land result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule

Section titled “warden schedule”
Timer-driven triggers the daemon fires for you: an agent or a pipeline, on a
recurring cron spec, at one set time, or right now.


A typical journey:
  1. create   warden schedule create nightly --cron "0 2 * * *" --prompt "..."
  2. look     warden schedule list, then warden schedule show nightly
  3. test     warden schedule run nightly (fires once now; next run unchanged)
  4. change   warden schedule edit nightly --cron "0 3 * * *"
  5. pause    warden schedule disable nightly, and enable to resume
  6. remove   warden schedule delete nightly


Nothing fires unless the scheduler is enabled (scheduler_enabled: true in the
config file) and the daemon is running. Runs a recurring schedule missed while
the daemon was down are not made up: it resumes at its next regular time.


Usage:
  warden schedule [flags]


Commands:
  create               Create a schedule that fires an agent or a pipeline
  list                 List schedules
  show                 Show one schedule, including its last-run outcome
  edit                 Edit a schedule's timing or fire payload
  run                  Fire a schedule once now without changing its next run
  enable               Enable a schedule so it fires again (re-arms next run)
  disable              Disable a schedule so it stops firing (history preserved)
  delete               Delete a schedule


Flags:
  -h, --help   help for schedule


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule create

Section titled “warden schedule create”
Create a recurring (--cron), single-shot (--at) or immediate (--now) schedule. By default a
schedule fires one agent, started the same way `warden start` would start it
with the same flags from the directory you run this in:
  --cwd <dir>    launch the agent in this existing directory (default: the
                 current directory, stored as an absolute path)
  --repo <path>  run the agent in an isolated worktree off this repo
                 (--branch picks the branch); replaces the --cwd default
  --role <role>  agent role, see `warden agent role list` (default: worker
                 with --repo, otherwise general)
  --prompt, --agent <name>   the agent's task and optional name
  --aicli <id>, --model <id>   the AI CLI and model to run (--model needs --aicli)
  --permission-mode, --auto-restart, --tags, --tier   as for `warden start`
  --project <id> the project the agent joins (default: the one owning its directory)
A schedule that could never fire (unknown role, missing directory, no
prompt) is rejected with the reason.


Pass --pipeline <spec.yaml> instead to fire a pipeline (its name is
timestamp-suffixed per fire so recurring runs don't collide). A pipeline runs as
written, so combining --pipeline with any agent option is an error.


Provide exactly one of --cron/--at/--now: --at must be in the future (a past
time is rejected) and --now fires once as soon as possible. --json prints the
created schedule.


Examples:
  # recurring agent: a weekday-morning review in the current directory
  warden schedule create morning-review --cron "0 9 * * 1-5" --role reviewer \
      --prompt "review yesterday's merged PRs and list follow-ups"
  # single-shot agent: a worktree off a repo, once, at a set time
  warden schedule create release-prep --at 2026-12-01T08:00 --repo ~/dev/app \
      --aicli claude --model sonnet --prompt "prepare the release notes"
  # recurring pipeline: a nightly spec file
  warden schedule create nightly --cron "@daily" --pipeline nightly.yaml


Usage:
  warden schedule create <name> (--cron <spec> | --at <time> | --now) [--prompt <s>] [--role <role>] [--cwd <dir> | --repo <path>] | --pipeline <spec.yaml> [flags]


Flags:
      --agent string             optional name for the spawned agent
      --aicli <ID>               AI CLI <ID>: claude (default, stable) | aider | opencode | codex | crush | goose | cursor | antigravity — only claude is fully tested; codex/antigravity are beta, the rest experimental. See 'warden backend --help' for per-AI-CLI notes
      --at string                single-shot time in the future, RFC3339 or 2006-01-02T15:04; a time without a zone is the local time of the machine running the daemon
      --auto-restart             auto-resume the agent if it crashes (errored), capped at a few attempts
      --branch string            optional development branch / pr-review checkout
      --cron string              recurring cron spec, e.g. "0 9 * * *" (minute hour dom month dow); evaluated in the daemon host's local time unless prefixed TZ=<zone>
      --cwd string               directory to launch the agent in (default: the current directory unless --repo is given)
  -h, --help                     help for create
      --json                     print the created schedule as JSON
      --model string             model ID for the chosen AI CLI (requires --aicli). Empty lets the tier resolver pick an explicit model
      --now                      fire once as soon as possible (a single-shot due immediately); exclusive with --cron and --at
      --permission-mode string   permission mode: acceptEdits|auto|bypassPermissions|default|dontAsk|plan (default: from config or 'auto')
      --pipeline string          fire a pipeline from this YAML spec file (instead of an agent)
      --project <ID>             <ID> of the daemon project the agent joins (its canonical path or remote URL, from 'warden projects list'). Empty = the git repository root of the launch directory
      --prompt string            the agent's initial prompt
      --repo string              repo path: the agent runs in an isolated worktree off it (default role worker)
      --role <ROLE>              agent role <ROLE>: general | autopilot | brain | orchestrator | planner | worker (legacy aliases implementer/auto-merger/reviewer resolve to worker) (default: worker with --repo, otherwise general)
      --tags <LIST>              comma-separated labels <LIST> stamped on every agent this schedule starts (e.g. --tags nightly,backend)
      --tier string              model tier for the quota-balanced resolver that picks the AI CLI+model: tier-1|tier-2|tier-3. An explicit --aicli/--model still wins


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule list

Section titled “warden schedule list”
List schedules as a table. Columns: NAME, STATE (enabled, disabled, done for a
single-shot that has fired, failed for a single-shot whose fire failed), WHEN
(the cron spec, or the single-shot time), FIRES (the agent and its role, or
the pipeline), NEXT (the next run, local time) and LAST (when it last ran and
how it went). A schedule whose last run failed has the error on the line
beneath it; a recurring one is still enabled and will try again.


--json prints the raw result.


Usage:
  warden schedule list [flags]


Examples:
  warden schedule list
    warden schedule ls --json


Flags:
  -h, --help   help for list
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden schedule show

Section titled “warden schedule show”
Show a schedule: its state, timing, next run and when it was created, then
what it fires in full (for an agent: the prompt, directory, repo, branch, role,
model, AI CLI and agent name; for a pipeline: its name and job count) and its
last run with the command to look at it. --spec also prints the stored
pipeline YAML. --json prints the raw record.


Usage:
  warden schedule show <id> [flags]


Examples:
  warden schedule show nightly
    warden schedule show nightly --spec
    warden schedule show nightly --json


Flags:
  -h, --help   help for show
      --json   output as JSON
      --spec   also print the stored pipeline YAML


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule edit

Section titled “warden schedule edit”
Change only the parts you pass; everything else stays as it is. Timing:
--cron or --at (switching a schedule between recurring and single-shot).
Payload: the agent options (--prompt, --role, --repo, --cwd, --branch, --model,
--aicli, --agent) or a new --pipeline spec file. An empty value clears an
optional field. --json prints the updated schedule.


Usage:
  warden schedule edit <id> [--cron <spec> | --at <time>] [agent flags] | --pipeline <spec.yaml> [flags]


Examples:
  warden schedule edit nightly --cron "0 3 * * *"
    warden schedule edit nightly --prompt ""


Flags:
      --agent string      agent name (empty clears it)
      --aicli string      AI CLI (empty clears it)
      --at string         new single-shot time in the future (switches from --cron)
      --branch string     development branch (empty clears it)
      --cron string       new recurring cron spec (switches from --at)
      --cwd string        agent launch directory (empty clears it)
  -h, --help              help for edit
      --json              print the updated schedule as JSON
      --model string      model ID (empty clears it)
      --pipeline string   new pipeline YAML spec file
      --prompt string     agent prompt (empty clears it)
      --repo string       repo path for an agent schedule
      --role string       agent role (empty clears it)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule run

Section titled “warden schedule run”
Fire the schedule's agent or pipeline once, right now, to test it. This does
not consume a single-shot or move a recurring schedule's next run, and it works
on a disabled schedule.


Usage:
  warden schedule run <id> [flags]


Examples:
  warden schedule run nightly


Flags:
  -h, --help   help for run


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule enable

Section titled “warden schedule enable”
Turn a disabled schedule back on and re-arm its next run from now. Says so when
the schedule was already enabled. --json prints {changed, schedule}.


Usage:
  warden schedule enable <id> [flags]


Examples:
  warden schedule enable nightly


Flags:
  -h, --help   help for enable
      --json   print {changed, schedule} as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule disable

Section titled “warden schedule disable”
Stop a schedule from firing without deleting it; its record and last-run
history are kept. Turn it back on with `warden schedule enable`. Says so when
the schedule was already disabled. --json prints {changed, schedule}.


Usage:
  warden schedule disable <id> [flags]


Examples:
  warden schedule disable nightly


Flags:
  -h, --help   help for disable
      --json   print {changed, schedule} as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden schedule delete

Section titled “warden schedule delete”
Delete a schedule permanently, after asking you to confirm. The prompt names the
schedule, what it fires and its next run. Only the schedule is removed: agents
and pipelines it already started keep running and are not affected. To stop a
schedule but keep it, use `warden schedule disable`.


Pass --yes/-y to skip the prompt; without a terminal on stdin, --yes is required.


Usage:
  warden schedule delete <id> [flags]


Examples:
  warden schedule delete nightly
    warden schedule rm nightly --yes


Flags:
  -h, --help   help for delete
  -y, --yes    skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  rm

warden project

Section titled “warden project”
Manage repo-local warden configuration: durable project memory, reusable
spawn presets and prompt templates, the library umbrella over saved launch
configs, and the plugin registry for custom task types and lifecycle hooks.


Usage:
  warden project [flags]


Commands:
  memory               Show or edit this repo's warden project memory (.warden/memory.md)
  preset               Save and list named spawn configs (replay with `warden start --preset <name>`)
  prompt-template      Save and list reusable, variabled prompt templates (fill with `warden start --prompt-template <name> --set VAR=value`)
  library              Browse saved spawn presets, prompt templates, and pipeline templates in one place
  plugin               Inspect warden's plugin system (#47): custom task types + lifecycle hooks


Flags:
  -h, --help   help for project


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project memory

Section titled “warden project memory”
Show or edit warden's project memory for the current repo — the committed,
backend-neutral .warden/memory.md (beside .warden/check.yml) holding durable,
cross-agent facts: where things live, how to run X, project invariants. Keeping
them here means the NEXT agent (any backend) doesn't re-pay the rediscovery tax.


The file is keyed implicitly by the repo root (git rev-parse --show-toplevel) and
auto-created on first use — no `wd init`, no registration. warden READS but never
rewrites your CLAUDE.md / AGENTS.md / CONVENTIONS.md; this file is warden's own.


With no flags it prints the resolved path and the budgeted, navigational view of
the memory — the SAME projection warden injects into every spawned agent's system
prompt (Claude via --append-system-prompt; other backends via their AGENTS.md /
CRUSH.md / .goosehints warden block). So `wd memory` shows exactly what the next
agent will read. Toggle the injection with the `memory.inject` config key (default
on); off, or an empty/absent file, is byte-identical to no injection.


Use --raw to print the file verbatim, --path for just the resolved path (handy in
scripts), and --edit to open it in $EDITOR (auto-creating it first if missing).


This verb is CLI-local (like `wd check` / `wd review`): it reads/writes the file
directly with no daemon round-trip. You curate the file by hand here; warden can
ALSO auto-propose entries from completion digests when the `memory.curate` config
key is on (default off) — those proposals land as `unverified` entries in the
working tree only (never committed/pushed), so the committed diff is the review
gate. See the Project memory concept page.


Usage:
  warden project memory [flags]


Flags:
  -e, --edit   open the memory file in $EDITOR (auto-creates it first)
  -h, --help   help for memory
      --path   print just the resolved file path (scriptable; no auto-create)
      --raw    print the file verbatim instead of the rendered view


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project preset

Section titled “warden project preset”
Save and list named spawn configs (replay with `warden start --preset <name>`)


Usage:
  warden project preset [flags]


Commands:
  list                 List saved presets and their defaults
  save                 Save the given spawn flags as a named preset


Flags:
  -h, --help   help for preset


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project preset list

Section titled “warden project preset list”
List saved presets and their defaults


Usage:
  warden project preset list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project preset save

Section titled “warden project preset save”
Persist a reusable set of `warden start` defaults under a name in
~/.warden/presets.yaml. Saving an existing name overwrites it. Replay with
`warden start --preset <name>` (explicit CLI flags still win).


Usage:
  warden project preset save <name> [spawn flags] [flags]


Flags:
      --auto-restart                auto-resume this agent if it crashes (errored)
  -h, --help                        help for save
      --in-repo                     run in the shared repo instead of an isolated worktree
      --model string                claude model: opus, sonnet, haiku, fable, or full model ID
      --permission-mode string      permission mode: acceptEdits|auto|bypassPermissions|default|dontAsk|plan
      --permission-posture string   Warden posture: read-only|read-write|allowlisted|dangerously-execute-all
      --supervised                  alias for --permission-mode acceptEdits
      --worktree                    create a scratch worktree for analysis/spike


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project prompt-template

Section titled “warden project prompt-template”
Save and list reusable, variabled prompt templates (fill with `warden start --prompt-template <name> --set VAR=value`)


Usage:
  warden project prompt-template [flags]


Commands:
  list                 List saved prompt templates and their variables
  save                 Save a named prompt template with {{VAR}} placeholders


Flags:
  -h, --help   help for prompt-template


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project prompt-template list

Section titled “warden project prompt-template list”
List saved prompt templates and their variables


Usage:
  warden project prompt-template list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project prompt-template save

Section titled “warden project prompt-template save”
Persist a reusable prompt body under a name in
~/.warden/prompt-templates.yaml. The body may contain `{{VAR}}` placeholders;
the declared variables are derived from the body automatically. Saving an
existing name overwrites it. Fill in and spawn with
`warden start --prompt-template <name> --set VAR=value …`.


Usage:
  warden project prompt-template save <name> --prompt "<body with {{VAR}} placeholders>" [flags]


Flags:
  -h, --help            help for save
      --prompt string   the template body, with {{VAR}} placeholders


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project library

Section titled “warden project library”
One umbrella over warden's reusable launch configs:
  • spawn PRESETS      — named `warden start` defaults (saved in ~/.warden/presets.yaml)
  • prompt TEMPLATES   — variabled prompt bodies (saved in ~/.warden/prompt-templates.yaml)
  • pipeline TEMPLATES — built-in DAG starters bundled with warden (read-only)


`library list` shows all three. `library save-preset` saves a spawn preset (the
same as `warden preset save`) and `library save-prompt` saves a prompt template
(the same as `warden prompt-template save`). Pipeline templates are embedded and
read-only, so there is no `save-template`; author a pipeline from a YAML spec with
`warden pipeline create <spec.yaml>` instead. The `preset`, `prompt-template`,
and `pipeline template list` commands remain available and unchanged.


Usage:
  warden project library [flags]


Commands:
  list                 List saved spawn presets and built-in pipeline templates


Flags:
  -h, --help   help for library


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project library list

Section titled “warden project library list”
Show all three libraries in labeled sections: saved spawn presets (name +
their stored defaults), prompt templates, and the built-in pipeline templates
(name + a short description). The pipeline templates section is the same catalog
as `wd pipeline template list`. Reuses the same sources as `warden preset list`
and `wd pipeline template list`.


Usage:
  warden project library list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project plugin

Section titled “warden project plugin”
Plugins are external executables registered in config (plugins.registry) that declare custom agent task types and subscribe to lifecycle hook events (pre/post spawn, commit, check, teardown), invoked over a JSON-over-stdio protocol. The system is OFF by default — plugins run external code — and every hook fails open (a broken/slow/missing plugin is logged and skipped, never blocking an agent).


Usage:
  warden project plugin [flags]


Commands:
  list                 List registered plugins, their custom task types, and subscribed hook events


Flags:
  -h, --help   help for plugin


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project plugin list

Section titled “warden project plugin list”
List registered plugins, their custom task types, and subscribed hook events


Usage:
  warden project plugin list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden projects

Section titled “warden projects”
Inspect and manage first-class daemon projects.


Projects represent checkout roots or remote repositories tracked by the
warden daemon. Agents and pipelines associate with these projects.


Subcommands allow listing, opening (local or remote), creating, and closing projects.
(For repo-local configuration like memory or presets, use `warden project`.)


Usage:
  warden projects [flags]


Commands:
  list                 List registered projects
  open                 Register or reopen a project by its canonical ID
  open-local           Register an existing local directory as a project
  open-remote          Clone a remote Git repository and register it as a project
  new                  Scaffold a brand-new project and register it
  close                Hibernate a project and gracefully stop its active agents


Flags:
  -h, --help   help for projects


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden projects list

Section titled “warden projects list”
List every project registered with the daemon, including open and closed (hibernated) projects.


Usage:
  warden projects list [flags]


Flags:
  -h, --help   help for list
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden projects open

Section titled “warden projects open”
Register or reopen a project by its canonical ID (checkout path or remote URL).


Usage:
  warden projects open <id> [flags]


Flags:
  -h, --help          help for open
      --name string   optional display name


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden projects open-local

Section titled “warden projects open-local”
Register an existing local directory as a project. The daemon normalizes the path and restores any hibernated agents.


Usage:
  warden projects open-local <path> [flags]


Flags:
  -h, --help          help for open-local
      --name string   optional display name


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden projects open-remote

Section titled “warden projects open-remote”
Clone a remote Git repository into the daemon workspace and register it as a project.


Usage:
  warden projects open-remote <url> [flags]


Flags:
  -h, --help          help for open-remote
      --name string   optional display name


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden projects new

Section titled “warden projects new”
Scaffold a brand-new project with git init and initial commit in the daemon workspace, and register it.


Usage:
  warden projects new <name> [flags]


Flags:
  -h, --help   help for new


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden projects close

Section titled “warden projects close”
Hibernate a project: keep the record in the store, set its status to closed, and gracefully stop its live agents.


Usage:
  warden projects close <id> [flags]


Flags:
  -h, --help   help for close


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups

Section titled “warden project-groups”
Inspect and manage project groups and their member projects.


A project group is a named collection of projects displayed together in the
cockpit TUI. Member projects carry the group label beside their name, and
orchestrators in the same group gain peer awareness of each other.


Usage:
  warden project-groups [flags]


Commands:
  list                 List project groups
  show                 Show details for a project group
  create               Create a new project group
  update               Update a project group's name and membership (bulk-set)
  delete               Delete a project group
  members              Manage project group members


Flags:
  -h, --help   help for project-groups


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups list

Section titled “warden project-groups list”
List all project groups with their member projects.


Usage:
  warden project-groups list [flags]


Flags:
  -h, --help   help for list
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden project-groups show

Section titled “warden project-groups show”
Show detailed information about a project group, including its member projects.


Usage:
  warden project-groups show <id> [flags]


Flags:
  -h, --help   help for show
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups create

Section titled “warden project-groups create”
Create a new named project group with optional initial member projects.


Usage:
  warden project-groups create <name> [flags]


Flags:
  -h, --help              help for create
  -p, --project strings   initial member project ID (repeatable)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups update

Section titled “warden project-groups update”
Update a project group's display name and/or overwrite its member project list.


Usage:
  warden project-groups update <id> [flags]


Flags:
  -h, --help              help for update
  -n, --name string       new display name
  -p, --project strings   member project IDs to set (repeatable; overwrites full membership)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups delete

Section titled “warden project-groups delete”
Delete a project group. Member projects remain registered and are not touched.


Usage:
  warden project-groups delete <id> [flags]


Flags:
  -h, --help   help for delete


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups members

Section titled “warden project-groups members”
Add or remove member projects in a project group incrementally.


Usage:
  warden project-groups members [flags]


Commands:
  add                  Add a project to a project group
  remove               Remove a project from a project group


Flags:
  -h, --help   help for members


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups members add

Section titled “warden project-groups members add”
Incrementally add a project (canonical ID, path, or URL) to a project group.


Usage:
  warden project-groups members add <group-id> <project-id> [flags]


Flags:
  -h, --help   help for add


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden project-groups members remove

Section titled “warden project-groups members remove”
Incrementally remove a project from a project group.


Usage:
  warden project-groups members remove <group-id> <project-id> [flags]


Flags:
  -h, --help   help for remove


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace

Section titled “warden workspace”
One umbrella over warden's workspace operations:
  • LIST worktrees — the warden-owned worktrees under .worktrees (`wd workspace list`)
  • PRUNE orphaned worktrees (`wd workspace prune`)
  • CLEAN merged branches and stale worktrees (`wd workspace clean`)
  • SNAPSHOT an agent's worktree + transcript (`wd workspace snapshot`)
  • BRANCHES — per-agent CI and branch-vs-main status (`wd workspace branches`)
  • CONFLICTS — files edited by more than one agent (`wd workspace conflicts`)
  • WHO-IS-EDITING — which agents are editing a file (`wd workspace who-is-editing`)


`wd workspace` with no subcommand prints the worktree list (the same view as `wd workspace list`).


Usage:
  warden workspace [flags]


Commands:
  list                 List warden worktrees under .worktrees, joined to active/archived records
  prune                Reclaim orphaned warden worktrees under .worktrees (always asks; --force overrides guards)
  clean                Delete merged local/origin branches and prune stale worktrees (previews, then asks)
  snapshot             Checkpoint an agent's worktree + transcript, list checkpoints, and restore one
  branches             Per-agent CI + branch-vs-main status
  conflicts            List files currently being edited by more than one agent
  who-is-editing       Show which agents are editing a specific file


Flags:
  -h, --help          help for workspace
      --json          output as JSON
      --repo string   repo path (default: current directory)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace list

Section titled “warden workspace list”
List warden worktrees under .worktrees, joined to active/archived records


Usage:
  warden workspace list [flags]


Flags:
  -h, --help          help for list
      --json          output as JSON
      --repo string   repo path (default: current directory)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace prune

Section titled “warden workspace prune”
Reclaim orphaned warden worktrees under .worktrees — those whose owning agent
record is gone (or, with --include-archived, archived). Always shows the plan
and asks before removing anything (skip with --yes); dirty/unpushed worktrees
are kept unless --force. Retention is policy-driven via the `worktree.keep_done`
/ `worktree.auto_prune` config settings.


Available as `wd worktree prune` and, unchanged, as the top-level alias `wd prune`.
(To tear down ONE agent's worktree instead, use `wd remove-worktree`.)


Usage:
  warden workspace prune [flags]


Flags:
      --dry-run            report what would be removed; change nothing
      --force              override the dirty/unpushed guard and permit branch deletion for record-less orphans (never the default branch)
  -h, --help               help for prune
      --include-archived   also reclaim worktrees owned by archived (done) records
      --json               output as JSON
      --repo string        repo path (default: current directory)
      --yes                skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace clean

Section titled “warden workspace clean”
Find branches and worktrees whose work already landed on the base branch —
including squash merges (detected via merged PRs from `gh`, `git cherry`, or a
trial merge) — show a preview, and after confirmation remove the stale
worktrees, delete the merged local branches, and delete the merged origin
branches in one coordinated operation (in that order).


main, master, develop, release/*, the base branch and the primary worktree's
branch are never deleted. Dirty worktrees are kept unless --force. Detection
runs `git fetch --prune origin` first (use --local-only to skip remote work).


Different from `wd workspace prune`, which reclaims ORPHANED warden worktrees
under .worktrees (agent record gone); clean targets MERGED branches and the
stale worktrees checked out on them.


Available as `wd workspace clean` and the top-level alias `wd clean`.


Usage:
  warden workspace clean [flags]


Flags:
      --dry-run       show what would be cleaned; change nothing
      --force         also remove dirty worktrees (does not bypass protected branches)
  -h, --help          help for clean
      --json          output as JSON (report for --dry-run, result otherwise)
      --local-only    skip remote (origin) branches and the fetch
      --repo string   repo path (default: current directory)
      --yes           skip the confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace snapshot

Section titled “warden workspace snapshot”
Capture a known-good point for an agent — its worktree state (a non-destructive
git stash, so the agent's tree is untouched) plus its session transcript — and
roll back to it later. Subcommands: create, list, restore.


Usage:
  warden workspace snapshot [flags]


Commands:
  create               Capture the worktree state + transcript of an agent (defaults to the current one)
  list                 List snapshots for an agent (newest first); --all for every session
  restore              Re-apply a snapshot onto its recorded worktree (refuses a dirty tree unless --force)


Flags:
  -h, --help   help for snapshot


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace snapshot create

Section titled “warden workspace snapshot create”
Capture a snapshot of an agent's worktree and session transcript. With no
[name] it snapshots the agent this command runs inside (WARDEN_SESSION_ID);
pass an agent id to snapshot a different one. The worktree is captured with
`git stash create` — non-destructive, so the agent's working tree is untouched.


Usage:
  warden workspace snapshot create [name] [flags]


Flags:
  -h, --help             help for create
      --json             emit the raw result as JSON
  -m, --message string   optional label for the snapshot


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace snapshot list

Section titled “warden workspace snapshot list”
List snapshots for an agent (newest first); --all for every session


Usage:
  warden workspace snapshot list [name] [flags]


Flags:
      --all    list snapshots across all sessions
  -h, --help   help for list
      --json   emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace snapshot restore

Section titled “warden workspace snapshot restore”
Re-apply a snapshot's captured worktree state onto the worktree it was taken
in. Refuses a dirty tree unless --force, and never restores onto main/master.
Reversible-safe: it re-applies the stash without resetting HEAD or dropping the
snapshot, so the snapshot stays usable and uncommitted work is the only thing at
risk (hence the dirty-tree guard).


Usage:
  warden workspace snapshot restore <snapshot-id> [flags]


Flags:
      --force   restore even when the worktree has uncommitted changes
  -h, --help    help for restore
      --json    emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace branches

Section titled “warden workspace branches”
Show each tracked agent's branch: its latest GitHub CI run and how it sits against origin/main (behind/ahead/merged).


Read-only. Requires the branch tracker to be enabled (branch_track.enabled); a disabled tracker reports no branches.


Usage:
  warden workspace branches [flags]


Flags:
  -h, --help   help for branches
      --json   output the branch statuses as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace conflicts

Section titled “warden workspace conflicts”
List files currently being edited by more than one agent


Usage:
  warden workspace conflicts [flags]


Flags:
  -h, --help   help for conflicts


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden workspace who-is-editing

Section titled “warden workspace who-is-editing”
Show which agents are editing a specific file


Usage:
  warden workspace who-is-editing <file> [flags]


Flags:
  -h, --help   help for who-is-editing


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git

Section titled “warden git”
Commit, push, sync, and review an agent worktree on warden rails.


Git verbs run locally in the agent's worktree (or the current directory when no
agent session is bound). They enforce branch rails, hook bookkeeping, and the
daemon-side session link — the high-frequency flat shortcuts `wd commit`,
`wd push`, and `wd sync` remain permanently supported wrappers.


Usage:
  warden git [flags]


Commands:
  commit               Stage and commit the worktree (warden rails + hooks + bookkeeping)
  push                 Push the current branch to origin (warden rails + bookkeeping)
  sync                 Fetch and rebase the current branch onto its base (warden conflict detect)
  pr                   Open (or return the already-open) pull request for the agent's branch
  review               Run the agent backend's native diff review on the worktree
  release              Recommend the next SemVer release tag, then tag and push it on confirmation


Flags:
  -h, --help   help for git


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git commit

Section titled “warden git commit”
Stage and commit every change in the current worktree on its branch.


warden refuses protected branches (main/master), runs pre-commit hooks and
returns only failures, and links the commit to this agent — one call in place
of the git status/add/commit/rev-parse round-trips.


Pass -m to author the message (best — you made the change). Omit it and warden
writes one: the local model from the staged diff if configured, otherwise a
deterministic conventional-commit message from the changed paths.


Give paths (relative to the current directory) to stage and commit only those;
paths outside the repository are rejected. With no paths everything is staged.


--amend rewrites the last commit, keeping its message unless -m is given. It is
refused on a merge commit and on a commit already in the upstream branch unless
--force (after which push needs --force-with-lease).


Usage:
  warden git commit [paths...] [flags]


Flags:
      --amend            rewrite the last commit (keeps its message unless -m is given)
      --force            with --amend, allow amending a commit already in the upstream branch
  -h, --help             help for commit
      --json             emit the raw result as JSON
  -m, --message string   commit message; if omitted, warden generates one from the diff


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git push

Section titled “warden git push”
Push the current worktree branch to origin, setting upstream.


warden refuses to push protected branches (main/master) directly — push your
agent branch and open a PR.


Pass --force-with-lease after a rebase or amend to overwrite your remote
branch. warden only ever uses --force-with-lease (never a bare --force), so
the push aborts if a teammate pushed to your branch since your last fetch.


Usage:
  warden git push [flags]


Flags:
      --force-with-lease   push with --force-with-lease (safe force after a rebase/amend)
  -h, --help               help for push
      --json               emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git sync

Section titled “warden git sync”
Fetch origin and rebase the current branch onto origin/<base> (default main).


Refuses a dirty tree (commit first). On conflict warden leaves the rebase in
progress and reports only the conflicting files for you to resolve.


While a rebase is in progress, `wd git sync --continue` stages your resolved files and
finishes it (reporting any conflicts from the next commit), and `wd git sync --abort`
drops it and restores the branch. A plain sync or `wd commit` is refused until then.


Exits non-zero when the rebase stops on conflicts.


Usage:
  warden git sync [flags]


Flags:
      --abort         drop a rebase in progress and restore the branch
      --base string   base branch to rebase onto (default main)
      --continue      finish a conflicted rebase: stage resolved files and run git rebase --continue
  -h, --help          help for sync
      --json          emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git pr

Section titled “warden git pr”
Push the agent's branch and open a GitHub pull request for it, without ending the
agent. Idempotent: when a PR is already open for the branch it is returned instead.


The agent comes from WARDEN_SESSION_ID (set in every warden-spawned session) or the
optional [agent-id] argument. Without either there is no agent to resolve a branch
and base from, so use `gh pr create` directly.


--base defaults like `wd git sync`: the agent's recorded base, its autopilot
integration branch, then the repository default. --title / --body (or --body-file,
`-` for stdin) are used verbatim; omitted ones are drafted from the agent's work.
main/master are refused as the PR head.


Usage:
  warden git pr [agent-id] [flags]


Flags:
      --base string        PR base branch (default: the agent's recorded base, resolved as for git sync)
      --body string        PR body (default: drafted from the agent's work)
      --body-file string   read the PR body from a file (- for stdin)
  -h, --help               help for pr
      --json               emit the raw result as JSON
      --title string       PR title (default: drafted from the agent's work)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git review

Section titled “warden git review”
Ask this agent's backend to review its own diff — the agent-native counterpart
to `wd check`. Where `wd check` runs the project's configured test/lint commands
and a reviewer-role agent stands up a whole reviewer session, `wd git review` invokes the
backend's OWN one-shot reviewer (Codex: `codex review`) against the worktree and
streams its findings to you — additive and on-top, no review session to manage.


By default it reviews the uncommitted working tree (staged + unstaged +
untracked); pass --base <branch> to review the branch's changes against a base
instead. The review runs locally in the agent's worktree (like a check); the
model/provider comes from the backend's own config, so the $0-local Ollama rig
and a paid setup both work unchanged.


Pass --json for a machine-readable result: warden runs the backend's structured
review (Codex: `codex exec review`), normalizes the backend's NATIVE review
output into a neutral findings shape ({summary, verdict, findings[]}), and prints
that JSON to stdout (the backend's own progress goes to stderr). Note: review
quality rides the backend's configured model — a tiny local model may report no
findings; the operator's real model is where this earns its keep.


Backends without a native review (e.g. Claude) are not offered the verb — it
exits non-zero pointing you at `wd check` or a reviewer-role agent.


Usage:
  warden git review [flags]


Flags:
      --ai-cli string   review for this backend id (default: the current agent's backend)
      --base string     review changes against this base branch (default: the uncommitted working tree)
  -h, --help            help for review
      --json            emit machine-readable findings (neutral JSON) instead of streaming the prose review
      --prompt string   optional extra review instructions for the backend's reviewer


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden git release

Section titled “warden git release”
Inspect commits since the latest SemVer tag and recommend the next release:
the bump (major/minor/patch), the next vMAJOR.MINOR.PATCH, and a categorized
changelog built from conventional commits and merged PRs.
A squash commit whose subject is not itself releasable (e.g. "autopilot: x (#1)")
is bumped by the conventional "* feat(...): ..." bullets in its body.


By default, the analysis targets origin/main (or origin/master) so releases are
evaluated against canonical upstream commits rather than uncommitted local edits
or active feature/agent worktrees. Pass --target to override.


This is the step after the final PR of a plan is merged.


Unless --no-fetch is given, the command fetches the target ref from origin first.


Interactive by default: asks before creating an annotated tag directly on the
target commit (default N), then — only if --push was given — asks before pushing
it to origin (default N). The tag message carries the rendered changelog. An
existing tag is never overwritten.


  --target <ref> set target ref to release (default: origin/main or origin/master)
  --no-fetch     skip fetching the target ref from origin before analysis
  --dry-run      print the recommendation only; never tag or push
  --yes          skip the create-tag prompt and create the annotated tag
  --push         push the tag to origin after it exists (prompts unless --yes)
  --yes --push   tag and push with no prompts
  --json         emit the advice and the actions taken as JSON


Agents should run `wd git release --dry-run`; pass --yes only when the operator
explicitly asked for a tag. Pushing a v* tag triggers the release pipeline.


Usage:
  warden git release [flags]


Flags:
      --dry-run         print the recommendation only; never tag or push
  -h, --help            help for release
      --json            emit the advice and actions taken as JSON
      --no-fetch        skip fetching target ref from origin before analysis
      --push            push the tag to origin after creating it (prompts unless --yes)
      --target string   target ref or branch to release (default: origin/main or origin/master)
      --yes             skip the create-tag prompt and create the annotated tag


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden check

Section titled “warden check”
Run project checks and install hook guards.


`wd check` (or `wd check run`) executes the commands declared in .warden/check.yml
and returns only failures. Guard subcommands are hook-facing entry points installed
by warden; they preserve the stdin/stdout JSON protocol and fail-open semantics of
the legacy `hook` paths. A configured check named list, run, guard, boundary,
or root-guard remains runnable as `wd check run <name>`.


Usage:
  warden check [name] [flags]


Commands:
  run                  Run the project's configured checks and report only failures
  list                 List configured project checks without running them


Flags:
  -h, --help   help for check
      --json   emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden check run

Section titled “warden check run”
Run the check command(s) declared in this project's .warden/check.yml and
return a pass/fail summary — with captured output for the FAILING checks only,
in place of the hundreds of lines a raw test run spills into the transcript.


`wd check run` runs every configured check; `wd check run <name>` runs one (e.g. test,
lint, build). Commands come from the project, so warden stays language-agnostic;
a repo with no .warden/check.yml has nothing to run. Exits non-zero on failure.


Usage:
  warden check run [name] [flags]


Flags:
  -h, --help   help for run
      --json   emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden check list

Section titled “warden check list”
List configured project checks without running them


Usage:
  warden check list [flags]


Flags:
  -h, --help   help for list
      --json   emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden context

Section titled “warden context”
Read and write the shared context (a namespaced key/value store agents share)


Usage:
  warden context [flags]


Commands:
  set                  Set a context key (value inline, or --file / --stdin)
  cas                  Set a key only if its current value matches --expected (atomic compare-and-set)
  append               Atomically append to a key's value (creates it if absent)
  get                  Print the value at a context key
  list                 List context keys (optionally filtered by prefix)
  delete               Delete a context key


Flags:
  -h, --help   help for context


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden context set

Section titled “warden context set”
Set a context key (value inline, or --file / --stdin)


Usage:
  warden context set <key> [value] [flags]


Flags:
      --as string     writer identity (defaults to $WARDEN_SESSION_ID or 'human')
      --file string   read value from a file
  -h, --help          help for set
      --stdin         read value from stdin


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden context cas

Section titled “warden context cas”
Set a key only if its current value matches --expected (atomic compare-and-set)


Usage:
  warden context cas <key> [value] [flags]


Flags:
      --as string         writer identity (defaults to $WARDEN_SESSION_ID or 'human')
      --expected string   only set if the current value equals this (empty = key must be absent)
      --file string       read value from a file
  -h, --help              help for cas
      --stdin             read value from stdin


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden context append

Section titled “warden context append”
Atomically append to a key's value (creates it if absent)


Usage:
  warden context append <key> [value] [flags]


Flags:
      --as string     writer identity (defaults to $WARDEN_SESSION_ID or 'human')
      --file string   read value from a file
  -h, --help          help for append
      --sep string    separator inserted before the value when the key already exists (default "\n")
      --stdin         read value from stdin


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden context get

Section titled “warden context get”
Print the value at a context key


Usage:
  warden context get <key> [flags]


Flags:
  -h, --help   help for get


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden context list

Section titled “warden context list”
List context keys (optionally filtered by prefix)


Usage:
  warden context list [prefix] [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden context delete

Section titled “warden context delete”
Delete a context key


Usage:
  warden context delete <key> [flags]


Flags:
  -h, --help   help for delete


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden message

Section titled “warden message”
Send and receive directed messages between agents


Usage:
  warden message [flags]


Commands:
  send                 Send a message to an agent (wakes it if it's idle/waiting)
  inbox                Show this agent's messages (marks them read)
  wait                 Block until a message arrives (or timeout), then print it


Flags:
  -h, --help   help for message


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden message send

Section titled “warden message send”
Send a message to an agent (wakes it if it's idle/waiting)


Usage:
  warden message send <to> <message...> [flags]


Flags:
  -h, --help   help for send


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --as string       act as this agent id (defaults to $WARDEN_SESSION_ID)
      --config string   config file path (default ~/.warden/config.yaml)

warden message inbox

Section titled “warden message inbox”
Show this agent's messages (marks them read)


Usage:
  warden message inbox [flags]


Flags:
  -h, --help     help for inbox
      --unread   show only unread messages


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --as string       act as this agent id (defaults to $WARDEN_SESSION_ID)
      --config string   config file path (default ~/.warden/config.yaml)

warden message wait

Section titled “warden message wait”
Block until a message arrives (or timeout), then print it


Usage:
  warden message wait [flags]


Flags:
      --from string   only wait for a message from this sender
  -h, --help          help for wait
      --timeout int   seconds to wait before giving up (daemon caps at 600) (default 300)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --as string       act as this agent id (defaults to $WARDEN_SESSION_ID)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval

Section titled “warden approval”
Manage tool-permission prompts and the auto-approve policy.


List pending prompts with list, answer recognized menus by option number with
answer, configure per-agent participation plus allow/deny rules under auto, and
inspect or forget the prompt shapes warden has learned under known.


Usage:
  warden approval [flags]


Commands:
  list                 List pending tool-permission prompts waiting for an answer
  answer               Answer a pending tool-permission prompt by option number
  auto                 Toggle per-agent auto-approve and manage the rule policy
  known                Inspect and forget learned prompt shapes


Flags:
  -h, --help   help for approval


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval list

Section titled “warden approval list”
List pending tool-permission prompts waiting for an answer


Usage:
  warden approval list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval answer

Section titled “warden approval answer”
Answer a pending tool-permission prompt by option number


Usage:
  warden approval answer <TICKET> <option> [flags]


Flags:
  -h, --help   help for answer


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto

Section titled “warden approval auto”
Control automatic approval of recognized tool-permission prompts.


Two layers cooperate:


  • Per-agent toggle (this command's bare form): opt one agent into evaluation
    even when the global policy is disabled.
        warden approval auto abc123 on    # participate
        warden approval auto abc123 off   # stop


  • Policy rules (the subcommands below): an allow/deny rule engine evaluated for
    every participating agent. A prompt is auto-answered only when it matches an
    allow rule, matches NO deny rule, and is not on warden's built-in destructive
    deny-list (which always wins). With NO rules configured the policy is the
    simple on/off toggle: an enabled policy approves every recognized,
    non-destructive prompt (backward compatible with the old behavior).


Rules match by tool name, a case-insensitive glob/substring (--pattern), a Go
regular expression (--regex) over the prompt, and/or path globs (--paths). A
per-agent override (--agent NAME, keyed by agent name or id) gets its own rule
set that replaces the default for that agent.


Examples:
  warden approval auto rules                         # show the live policy
  warden approval auto enable                        # turn the policy on
  warden approval auto allow --tool Read             # auto-approve all Read prompts
  warden approval auto allow --regex '^Bash\(git (status|diff|log)\)'
  warden approval auto deny  --tool Bash --pattern rm
  warden approval auto allow --agent reviewer --tool Grep
  warden approval auto clear --agent reviewer        # drop reviewer's overrides


Rule changes take effect immediately (no restart) and are persisted to config.


Usage:
  warden approval auto [flags]


Commands:
  set                  Toggle per-agent auto-approve participation
  rules                Show the live auto-approve policy (default rules + per-agent overrides)
  allow                Append an allow rule to the auto-approve policy
  deny                 Append an deny rule to the auto-approve policy
  clear                Clear auto-approve rules (default, or a per-agent override with --agent)
  enable               Enable the auto-approve policy (global, or per-agent with --agent)
  disable              Disable the auto-approve policy (global, or per-agent with --agent)


Flags:
  -h, --help   help for auto


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto set

Section titled “warden approval auto set”
Toggle per-agent auto-approve participation


Usage:
  warden approval auto set <agent-id> <on|off> [flags]


Flags:
  -h, --help   help for set


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto rules

Section titled “warden approval auto rules”
Show the live auto-approve policy (default rules + per-agent overrides)


Usage:
  warden approval auto rules [flags]


Flags:
  -h, --help   help for rules


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto allow

Section titled “warden approval auto allow”
Append an allow rule to the auto-approve policy


Usage:
  warden approval auto allow [flags]


Flags:
      --agent string     scope the rule to a per-agent override (agent name or id)
  -h, --help             help for allow
      --paths strings    path globs against the action target (comma-separated)
      --pattern string   case-insensitive glob/substring over the action + question
      --regex string     Go regular expression over the action + question
      --tool string      exact tool name to match (e.g. Read, Bash)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto deny

Section titled “warden approval auto deny”
Append an deny rule to the auto-approve policy


Usage:
  warden approval auto deny [flags]


Flags:
      --agent string     scope the rule to a per-agent override (agent name or id)
  -h, --help             help for deny
      --paths strings    path globs against the action target (comma-separated)
      --pattern string   case-insensitive glob/substring over the action + question
      --regex string     Go regular expression over the action + question
      --tool string      exact tool name to match (e.g. Read, Bash)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto clear

Section titled “warden approval auto clear”
Clear auto-approve rules (default, or a per-agent override with --agent)


Usage:
  warden approval auto clear [flags]


Flags:
      --agent string   clear a per-agent override (agent name or id) instead of the default rules
  -h, --help           help for clear


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto enable

Section titled “warden approval auto enable”
Enable the auto-approve policy (global, or per-agent with --agent)


Usage:
  warden approval auto enable [flags]


Flags:
      --agent string   toggle a per-agent override (agent name or id) instead of the global default
  -h, --help           help for enable


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval auto disable

Section titled “warden approval auto disable”
Disable the auto-approve policy (global, or per-agent with --agent)


Usage:
  warden approval auto disable [flags]


Flags:
      --agent string   toggle a per-agent override (agent name or id) instead of the global default
  -h, --help           help for disable


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval known

Section titled “warden approval known”
Inspect and forget the known-prompts store.


When the Fast-Brain reads a permission prompt no backend parser recognizes, warden
remembers its SHAPE (templated question + option labels, never the concrete
command or path) so the next occurrence is recognized without a model call. Use
list to see what was learned and forget to drop an entry that was learned wrong.


Usage:
  warden approval known [flags]


Commands:
  list                 List learned prompt shapes (id, backend, question, options, hits, last seen)
  forget               Forget one learned prompt shape, or all with --all


Flags:
  -h, --help   help for known


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval known list

Section titled “warden approval known list”
List learned prompt shapes (id, backend, question, options, hits, last seen)


Usage:
  warden approval known list [flags]


Examples:
  warden approval known list
    warden approval known list --json


Flags:
  -h, --help   help for list
      --json   emit the entries as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden approval known forget

Section titled “warden approval known forget”
Forget a learned prompt shape by id (see approval known list). The prompt is
re-learned the next time it appears. With --all, empties the whole store after a
confirmation prompt (skip it with --yes). Forget actions are audit-logged.


Usage:
  warden approval known forget [ID] [flags]


Examples:
  warden approval known forget 3f9a1c0d2b7e4a65c8d1e0f2
    warden approval known forget --all --yes


Flags:
      --all    forget every learned prompt shape
  -h, --help   help for forget
      --json   emit the result as JSON
      --yes    skip the confirmation prompt for --all


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect

Section titled “warden inspect”
Search, audit, export, repair, and measure warden's fleet and resources.


Resource samples (CPU, memory, pressure, daemon stats) live under `resources`.
Financial usage and provider quota snapshots live under `usage`, not here.


Usage:
  warden inspect [flags]


Commands:
  resources            Show warden's resource footprint (per-agent memory/CPU, system pressure, daemon stats)
  search               Full-text search agents by subject, prompt, type, name, branch, or pane text
  history              Browse archived (closed) agents, newest first
  audit                Show recent audited actions, newest last
  export               Serialize agent session metadata to JSON on stdout
  import               Insert agent session metadata from a JSON dump on stdin
  fastbrain            Fast-Brain/Thinking-Brain telemetry, traces and per-kind pause/resume
  pty                  PTY runtime status, decision trace and metrics
  repair               Offline, backup-first repair tools
  legacy               Read-only inspection of retained schema-1 stores vs warden-db


Flags:
  -h, --help   help for inspect


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect resources

Section titled “warden inspect resources”
Show warden's resource footprint (per-agent memory/CPU, system pressure, daemon stats)


Usage:
  warden inspect resources [flags]


Flags:
      --agent string   with --history, limit to one agent ID
  -h, --help           help for resources
      --history        show persisted per-agent performance history + anomaly warnings
      --json           output as JSON
      --watch          redraw every 3s until interrupted


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)
Section titled “warden inspect search”
Search across active agents' searchable text (name, id, ticket, type, subject, prompt, branch, last pane excerpt). Multiple terms are AND-ed. Pass --closed to also search archived agents.


Usage:
  warden inspect search <QUERY...> [flags]


Flags:
      --closed   also search archived (closed) agents
  -h, --help     help for search
      --json     output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect history

Section titled “warden inspect history”
List the archived agent records the soft-delete path persists. Filter with --since (24h, 7d, 2w, or a date) and --role.


Usage:
  warden inspect history [flags]


Flags:
  -h, --help           help for history
      --json           output as JSON
      --limit int      cap the number of results (0 = no cap)
      --role string    filter by role (general, worker, orchestrator, …)
      --since string   only agents updated since this window (24h, 7d, 2w) or date (2006-01-02 / RFC3339)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect audit

Section titled “warden inspect audit”
Print audit records in chronological order. Tail the most recent with --tail (0 = all), and narrow with --action, --target, and --since/--until.


Usage:
  warden inspect audit [flags]


Flags:
      --action string   filter by action (spawn, terminate, delete, approve, pipeline_start, pipeline_cancel)
  -h, --help            help for audit
      --json            output as JSON
      --since string    only records since this window (24h, 7d, 2w) or date (2006-01-02 / RFC3339)
      --tail int        show only the most recent N records (0 = all) (default 50)
      --target string   filter by target substring (agent or pipeline ID)
      --until string    only records up to this window or date


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect export

Section titled “warden inspect export”
Dump active agent records as a JSON envelope on stdout, for backup, sharing, or migration. Metadata only — worktrees, branches, and tmux sessions are NOT serialized and `warden import` does not recreate them.


With --all the archived (closed) records are included too.


  warden inspect export --all > backup.json


Usage:
  warden inspect export [flags]


Flags:
      --all    also include archived (closed) agents
  -h, --help   help for export


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect import

Section titled “warden inspect import”
Read a `warden export` envelope from stdin and insert its records into the store. Metadata only: worktrees and tmux sessions are NOT recreated — an imported record just remembers where its (now absent) worktree used to live.


Idempotent by id: a record whose id already exists is skipped, so re-importing the same dump is a no-op. Pass --merge to overwrite colliding records with the imported data instead.


  warden inspect import < backup.json


Usage:
  warden inspect import [flags]


Flags:
  -h, --help    help for import
      --json    output the import result as JSON
      --merge   overwrite existing records on id collision (default: skip)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect fastbrain

Section titled “warden inspect fastbrain”
Inspect warden's own internal decisions (approval arbitration, stall triage,
commit/PR drafting, activity summaries, ...) without exposing their content.


status     per-kind attempts, outcomes, cache/coalesce/shed counters, queue
           wait and run-time percentiles, runner circuit state and pauses
decisions  the recent redacted decision trace (newest first)
pause      pause one decision kind; its calls fail open without a model call
resume     clear a pause


Labels are bounded to decision kind, tier, outcome, provider (AI CLI) and
model. Prompts, outputs, agent/session ids and paths are never reported. A
pause defaults to 1h and is capped at 24h; a daemon restart clears operator
pauses (config fast_brain.disabled_kinds pauses persist). Pausing never
changes the destructive-action guard: paused arbitration escalates to a human.


Usage:
  warden inspect fastbrain [flags]


Commands:
  decisions            Show recent redacted decision traces
  pause                Pause one decision kind (fails open, no model call)
  resume               Resume a paused decision kind
  status               Show Fast-Brain/Thinking-Brain telemetry


Flags:
  -h, --help   help for fastbrain


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect fastbrain decisions

Section titled “warden inspect fastbrain decisions”
Show recent redacted decision traces


Usage:
  warden inspect fastbrain decisions [flags]


Flags:
  -h, --help        help for decisions
      --json        emit the decisions as JSON
      --limit int   maximum decisions to show (default 50)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect fastbrain pause

Section titled “warden inspect fastbrain pause”
Pause one decision kind for a bounded time (default 1h, max 24h). Calls of
that kind return a deferred/fail-open result immediately without invoking a
runner. Resume with "warden inspect fastbrain resume KIND"; a daemon restart
also clears the pause. Audit-logged.


Usage:
  warden inspect fastbrain pause KIND [flags]


Examples:
  warden inspect fastbrain pause summarize_activity --for 2h


Flags:
      --for duration   pause duration (0 = default 1h, capped at 24h)
  -h, --help           help for pause


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect fastbrain resume

Section titled “warden inspect fastbrain resume”
Resume a paused decision kind


Usage:
  warden inspect fastbrain resume KIND [flags]


Flags:
  -h, --help   help for resume


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect fastbrain status

Section titled “warden inspect fastbrain status”
Show Fast-Brain/Thinking-Brain telemetry


Usage:
  warden inspect fastbrain status [flags]


Examples:
  warden inspect fastbrain status
    warden inspect fastbrain status --json


Flags:
  -h, --help   help for status
      --json   emit the snapshot as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect pty

Section titled “warden inspect pty”
Inspect the PTY runtime (runtime.pty: shadow|on) and the permission
decision engine built on it.


runtime <id>    live state with typed waiting reason and evidence, who owns the
                input line, the effective permission posture (a conspicuous
                banner for dangerously-execute-all), the latest decision route
                and a plain-language summary of the prompt on screen
decisions <id>  the append-only, redacted decision trace for the session: one
                record per auto-approve attempt/outcome (newest first)
metrics         the stable warden_pty_* metric families (JSON with --json)


Nothing here ever shows raw keystrokes or secrets: traces and metric labels are
redacted and bounded. Retention: runtime.trace_max_records / trace_max_age_days.


Usage:
  warden inspect pty [flags]


Commands:
  decisions            Show a session's redacted auto-approve decision trace
  metrics              Show the warden_pty_* metrics
  runtime              Show a session's live PTY-runtime status


Flags:
  -h, --help   help for pty


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect pty decisions

Section titled “warden inspect pty decisions”
Show a session's redacted auto-approve decision trace


Usage:
  warden inspect pty decisions <id> [flags]


Examples:
  warden inspect pty decisions A-1 --limit 20
    warden inspect pty decisions A-1 --outcome escalated_human


Flags:
  -h, --help             help for decisions
      --json             emit the records as JSON
      --limit int        maximum records (newest first) (default 50)
      --outcome string   only this outcome (approved, denied, dry_run, deferred, escalated_human, needs_attention, routed_brain, error)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect pty metrics

Section titled “warden inspect pty metrics”
Show the warden_pty_* metrics


Usage:
  warden inspect pty metrics [flags]


Flags:
  -h, --help   help for metrics
      --json   emit the snapshot as JSON instead of Prometheus text


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect pty runtime

Section titled “warden inspect pty runtime”
Show a session's live PTY-runtime status


Usage:
  warden inspect pty runtime <id> [flags]


Examples:
  warden inspect pty runtime A-1
    warden inspect pty runtime A-1 --json


Flags:
  -h, --help   help for runtime
      --json   emit the runtime view as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect repair

Section titled “warden inspect repair”
Offline, backup-first repair tools


Usage:
  warden inspect repair [flags]


Commands:
  agents               [schema 1 only; on schema 2 use `repair warden-db`] Verify or repair the agent store offline, backup-first
  all                  [schema 1 only; on schema 2 use `repair warden-db`] Rebuild all ScrivaDB stores offline using live-wins record resolution
  backends             [schema 1 only; on schema 2 use `repair warden-db`] Verify or repair the backend registry offline, backup-first
  sessions             [schema 1 only; on schema 2 use `repair warden-db`] Diagnose or reconstruct the offline session store
  warden-db            Verify or repair unified storage offline, backup-first


Flags:
  -h, --help   help for repair


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect repair agents

Section titled “warden inspect repair agents”
Offline repair of the agent store (<data>/agents-db).


The daemon must be stopped. --dry-run is read-only; repair uses ScrivaDB's
verified backup, atomic journaled repair, and conflict-preserving report.


Usage:
  warden inspect repair agents [flags]


Flags:
      --backup-dir string    parent directory for the verified repair backup
      --dry-run              verify and report only; do not modify files
  -h, --help                 help for agents
      --json                 print the machine-readable Verify/Repair report
      --on-conflict string   report or abort on ambiguous history (default "report")
      --salvage              permit ScrivaDB's conflict-safe segment salvage


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect repair all

Section titled “warden inspect repair all”
Offline, backup-first rebuild of all ScrivaDB stores in the Warden data directory.


Scans every ScrivaDB collection across all stores, keeping the latest valid record
for each _key and discarding stale revision regressions and stray records (where body id != _key).
Before modifying any files, a full backup of the stores is taken. Existing segment and index
files are quarantined into <collection>/quarantine/<runID>/ with a manifest, and clean segment
and index files are rebuilt and verified.


The daemon must be stopped before running this command.


Usage:
  warden inspect repair all [flags]


Flags:
      --backup-dir string        parent directory for pre-repair backup (default <data>/backups)
      --config string            config file path
      --dry-run                  inspect and report repair actions without modifying data
  -h, --help                     help for all
      --json                     print the machine-readable repair report as JSON
      --resolve-history string   resolution policy for conflicting revision history (only 'live-wins' supported) (default "live-wins")
  -y, --yes                      confirm repair without interactive prompt


Inherited flags:
      --addr string   daemon address (overrides the addr config setting)

warden inspect repair backends

Section titled “warden inspect repair backends”
Offline verify/repair of the backend registry (<data>/backends): backend rows,
tiers, enabled flags, default backend, settings, models, role tiers, quotas,
rate-limit cooldowns and handover settings.


The daemon must be stopped: the command refuses while any process owns the data
directory and names the owner and the stop command (with the systemd user
service: systemctl --user stop warden). Never start a second "warden daemon"
beside the service to work around it.


  warden inspect repair backends --dry-run   read-only: classify every finding, change nothing
  warden inspect repair backends             repair after an explicit confirmation


Each finding is classified as safely-recoverable (provably stale revision
history or a stale derived index) or recovery-required (ambiguous history or
damaged bytes). Repair takes a verified backup first, removes only provably
stale revisions (each one is listed in the report and kept in the backup), and
verifies the result; on any failure the backup is restored. Ambiguous history is
never resolved automatically: it is reported and the registry is left untouched.
A clean registry is a no-op.


Repair needs confirmation: answer the prompt, or pass --yes when not on a
terminal. Without either it refuses and changes nothing.


Exit codes:
  0  clean (nothing to do), or repaired and verified
  1  unexpected error
  3  refused: a running process owns the data directory
  4  recovery required: ambiguous findings, or the repair failed and was rolled back
  5  confirmation missing or declined
  6  --dry-run found safely recoverable findings (run without --dry-run to repair)


Usage:
  warden inspect repair backends [flags]


Examples:
  systemctl --user stop warden
    warden inspect repair backends --dry-run
    warden inspect repair backends
    systemctl --user start warden


    warden inspect repair backends --yes --json


Flags:
      --backup-dir string   parent directory for the verified backup and the report (default <data>/backend-registry-backups; must be outside <data>/backends)
      --dry-run             verify and report only; read-only, changes nothing
  -h, --help                help for backends
      --json                print the machine-readable report
  -y, --yes                 confirm the repair without prompting (required when not on a terminal)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect repair sessions

Section titled “warden inspect repair sessions”
[schema 1 only; on schema 2 use `repair warden-db`] Diagnose or reconstruct the offline session store


Usage:
  warden inspect repair sessions [flags]


Flags:
      --apply           apply the reconstruction (default is dry-run)
      --backup string   backup destination (required with --apply; must not exist)
      --dry-run         diagnose and report without changing session data
  -h, --help            help for sessions
      --json            print the machine-readable recovery report


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect repair warden-db

Section titled “warden inspect repair warden-db”
Offline repair of the schema-2 unified store (<data>/warden-db).


The daemon must be stopped. --dry-run is read-only. Repair requires a backup
directory outside warden-db and refuses ambiguous history rather than guessing.


Usage:
  warden inspect repair warden-db [flags]


Flags:
      --backup-dir string   directory for the verified pre-repair backup
      --dry-run             verify and report only; do not modify files
  -h, --help                help for warden-db
      --json                print the machine-readable Verify/Repair report
      --salvage             permit quarantining damaged segments after backing up valid records


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden inspect legacy

Section titled “warden inspect legacy”
Inspect the legacy schema-1 stores kept on disk after the schema-2 cutover:
legacy source paths, per-collection record counts compared with the canonical
warden-db, and the cutover backup's verification evidence.


Strictly read-only and never an authority: legacy stores are opened only
through private copies, nothing is written to the data dir (a before/after
fingerprint must match), and a data dir that has not cut over to schema 2 is
refused because there the legacy stores are the live authority. Canonical-only
records are expected after runtime use. Legacy data is never deleted.


Usage:
  warden inspect legacy [flags]


Flags:
      --data-dir string   path to the Warden data directory
  -h, --help              help for legacy
      --json              output results in JSON format


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend

Section titled “warden backend”
Inspect and manage warden's agent-backend registry.


warden detects the coding-agent CLIs installed on this machine (claude, codex,
aider, …), and persists each with a billing tier, an enabled flag, and at most
one default. The daemon's store is the source of truth — autopilot's cost-tier
ladder reads from it.


Tiers:   free | subscription | pay_per_use | unclassified


AI CLI notes (for 'warden agent start --aicli <ID>'):
  claude       default, stable; the only fully tested AI CLI, full-fidelity spend.
  codex        beta. BYO provider (~/.codex/config.toml); resumes (dir-scoped).
  antigravity  beta. Google-hosted agy; defaults gemini-3.5-flash; pass --model
               (see 'warden backend model'); resumes (dir-scoped agy -c).
  opencode     experimental. BYO model (--model with --aicli); structured
               transcript; resumes.
  aider        experimental. BYO model (--model with --aicli); runs a one-shot
               --message task; no resume.
  crush        experimental. BYO model (config-driven TUI; --model for headless);
               resumes (dir-scoped); initial prompt auto-typed post-launch.
  goose        experimental. BYO provider (GOOSE_PROVIDER/GOOSE_MODEL env); resumes
               (name-deterministic); no --model on session launch.
  cursor       experimental. Hosted model catalog; --model overrides; resumes
               (dir-scoped --continue); warden owns the worktree (cursor's -w unused).
All non-claude AI CLIs show tokens-only spend.


Examples:
  warden backend backend list                 # full table of detected backends
  warden backend backend rescan               # re-detect installed CLIs, print the table
  warden backend backend tier codex free      # tier codex as a $0 backend
  warden backend backend default claude       # make claude the default backend
  warden backend backend disable aider        # stop using a backend


Usage:
  warden backend [flags]


Commands:
  default              Set the default backend (rejects the reserved local row)
  disable              Disable a backend so it is no longer used
  enable               Enable a backend so it may be used
  list                 List detected backends (installed, tier, default, enabled, limited)
  rescan               Re-detect installed backend CLIs and print the updated table
  tier                 Set a backend's billing tier (free|subscription|pay_per_use|unclassified)
  model                Inspect and manage model catalog and live model menus
  suggest              Retired — Fast-Brain replaced local_llm
  repl                 Interactive REPL for agents, pipelines, and the git/check lifecycle (Fast-Brain + `/` commands).


Flags:
  -h, --help   help for backend


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend default

Section titled “warden backend default”
Make <id> the single default backend used when spawning agents without an
explicit backend. The daemon rejects an unknown, uninstalled, disabled, or
reserved (local) target.


Usage:
  warden backend default <id> [flags]


Flags:
  -h, --help   help for default


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend disable

Section titled “warden backend disable”
Disable a backend so it is no longer used


Usage:
  warden backend disable <id> [flags]


Flags:
  -h, --help   help for disable


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend enable

Section titled “warden backend enable”
Enable a backend so it may be used


Usage:
  warden backend enable <id> [flags]


Flags:
  -h, --help   help for enable


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend list

Section titled “warden backend list”
List every backend in the registry, with its
installed state, billing tier, whether it is the default, whether it is enabled,
and whether it is currently rate-limited. The current internal-thinking mode is
printed below the table.


Usage:
  warden backend list [flags]


Flags:
  -h, --help   help for list


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden backend rescan

Section titled “warden backend rescan”
Re-run backend detection and reconcile the registry: newly installed CLIs are
added and no-longer-present ones are marked uninstalled, while each backend's
tier, default, and enabled preferences are preserved. Prints the refreshed table.


Usage:
  warden backend rescan [flags]


Flags:
  -h, --help   help for rescan


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend tier

Section titled “warden backend tier”
Set a backend's billing tier. The tier drives autopilot's cost-tier ladder and
the internal free/local thinking router (only free backends are called for
internal thinking).


Valid tiers:
  free           # a $0 backend (free plan)
  subscription   # covered by a flat subscription
  pay_per_use    # metered / pay-as-you-go
  unclassified   # not yet tiered (treated as not free)


The reserved `local` tier is system-set and cannot be assigned.


Usage:
  warden backend tier <id> <tier> [flags]


Flags:
  -h, --help   help for tier


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model

Section titled “warden backend model”
Show the live, currently-available model menu the agent's backend exposes, or
inspect and configure the tiered model catalog in warden.


Subcommands:
  list      List models in the catalog and their assigned tiers
  tier      Set a model's tier classification (tier-1|tier-2|tier-3)
  add       Register a custom model in the catalog at runtime
  discover  Probe installed AI CLIs for live model menus
  refresh   Preview/apply a catalog refresh through the daemon (--apply --yes)
  history   Show catalog evidence and revisions
  rollback  Roll back a catalog revision (--yes)


When run without subcommands, `warden backend model` shows the live model menu of the
current or specified backend.


Usage:
  warden backend model [flags]


Commands:
  add                  Register a custom model in the catalog
  discover             Probe installed AI CLIs for live model menus
  history              Show catalog evidence and revision history
  list                 List models in the catalog and their assigned tiers
  refresh              Preview (and with --apply --yes, apply) a model-catalog refresh via the daemon
  rollback             Roll back a catalog policy revision
  tier                 Set a model's tier classification (tier-1|tier-2|tier-3)


Flags:
      --backend string   list models for this backend id (default: the current agent's backend)
  -h, --help             help for model
      --json             emit the menu as a JSON array instead of one id per line


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model add

Section titled “warden backend model add”
Insert a new model into warden's catalog at runtime.


The model is marked custom so seed pruning never removes it. Use this when a
backend gains a model that is not in the built-in seed (or after
`warden backend model discover` surfaces a live id you want to route).


Tiers:
  tier-1   Highest-capability models
  tier-2   Standard implementation models
  tier-3   Fast, low-cost models


Examples:
  warden backend model add cursor my-model --tier tier-2 --display "My Model" --auto-assign
  warden backend model add opencode ollama/qwen2.5-coder:3b --tier tier-3 --quota-scope default


Usage:
  warden backend model add <aicli> <model> [flags]


Flags:
      --auto-assign          include the model in quota-balanced AutoAssign routing
      --display string       human-readable display name (default: the model id)
  -h, --help                 help for add
      --quota-scope string   quota scope tag this model consumes (blank = default)
      --tier string          model tier (tier-1|tier-2|tier-3) (required)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model discover

Section titled “warden backend model discover”
Discover model ids from installed AI CLI tools and optionally import them
into the catalog.


Sources (when the tool is installed / the file is readable):
  cursor        cursor-agent --list-models
  antigravity   agy models
  opencode      opencode models
  crush         crush models
  codex         ~/.codex/config.toml (top-level model = "…")


By default this only lists what was discovered. Pass --import --tier <tier> to
register missing models as custom catalog entries (already-present ids are
skipped).


Examples:
  warden backend model discover
  warden backend model discover --backend cursor --json
  warden backend model discover --import --tier tier-2 --auto-assign


Usage:
  warden backend model discover [flags]


Flags:
      --auto-assign          mark imported models AutoAssign (with --import)
      --backend string       limit discovery to this backend id (cursor|antigravity|opencode|crush|codex)
  -h, --help                 help for discover
      --import               register discovered models missing from the catalog
      --json                 emit discovered models as a JSON array
      --quota-scope string   quota scope for imported models (with --import)
      --tier string          tier to assign when --import is set (tier-1|tier-2|tier-3)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model history

Section titled “warden backend model history”
Show catalog evidence and revision history


Usage:
  warden backend model history [flags]


Flags:
      --aicli string   filter evidence by AI CLI (account-safe; no credentials are shown)
  -h, --help           help for history
      --json           emit structured history


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model list

Section titled “warden backend model list”
List models in the catalog and their assigned tiers


Usage:
  warden backend model list [flags]


Flags:
      --backend string   filter models by backend ID
      --by-tier          group and display models by tier
  -h, --help             help for list
      --json             emit models as a JSON array
      --tier string      filter models by tier (tier-1|tier-2|tier-3)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)


Aliases:
  ls

warden backend model refresh

Section titled “warden backend model refresh”
Discover the models each installed AI CLI reports about itself (local files and
non-generating metadata commands only: no prompt, no login, no token read),
submit that evidence to the daemon as a catalog proposal, and print the diff.


Without --apply this is a preview: it records evidence and a proposal but never
changes routing policy. With --apply --yes it applies exactly the proposals it
just created (blocked operations are reported, never applied). A stale or expired
proposal is refused: re-run. Partial, empty, failed or offline discovery never
retires a model.


Applying changes catalog policy only. Pinned models (explicit --aicli + --model),
running, restored, forked, scheduled and pipeline sessions are untouched. To move
an existing agent onto the refreshed catalog, run an explicit hot-swap afterwards:
  warden switch AGENT --aicli ID --tier tier-N     (catalog pick within that AI CLI)
  warden switch AGENT --tier tier-N                (router pick across AI CLIs)
  warden switch AGENT --aicli ID --model MODEL     (explicit pin)


Examples:
  warden backend model refresh --aicli cursor
  warden backend model refresh --aicli cursor --aicli codex --json
  warden backend model refresh --apply --yes


Usage:
  warden backend model refresh [flags]


Flags:
      --aicli stringArray   limit to this AI CLI (repeatable; default: every installed AI CLI that can discover models)
      --apply               apply the proposals this command creates (requires --yes)
  -h, --help                help for refresh
      --json                emit structured per-aicli results
      --yes                 confirm --apply


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model rollback

Section titled “warden backend model rollback”
Roll back a catalog policy revision


Usage:
  warden backend model rollback <revision> [flags]


Flags:
  -h, --help   help for rollback
      --json   emit structured result
      --yes    confirm the catalog-policy rollback


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend model tier

Section titled “warden backend model tier”
Set a model's tier classification in the catalog.


Tiers:
  tier-1   Highest-capability models (e.g. Claude Opus, o1) for architecture, design, and complex planning
  tier-2   Standard implementation models (e.g. Claude Sonnet, Gemini Pro, GPT-4.1) for everyday coding
  tier-3   Fast, low-cost models (e.g. Claude Haiku, Gemini Flash, GPT-4.1-mini) for quick tasks and CI triage


Example:
  warden backend model tier claude sonnet tier-2


Usage:
  warden backend model tier <backend> <model> <tier> [flags]


Flags:
  -h, --help   help for tier


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend suggest

Section titled “warden backend suggest”
Retired. warden no longer runs a local model: the REPL (wd repl) and
internal thinking use Fast-Brain, so there is no local model to size or pull.
This command is kept for compatibility and exits 0.


Usage:
  warden backend suggest [flags]


Flags:
  -h, --help   help for suggest


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden backend repl

Section titled “warden backend repl”
Interactive mode: a full-screen-free REPL to drive your warden fleet from the terminal.


It is a real line editor — arrow keys, history (persisted across sessions),
reverse-search, and Tab completion — that closes cleanly with Ctrl-D, returning
you to your shell prompt.


Two ways to drive it:
  • Deterministic `/` commands (no model): /agents, /spawn <prompt>, /tell <id> <text>,
    /memory <question>, /pipelines, … — typing / pops a live, filtering menu of verbs;
    Tab also completes verbs and live agent ids. Type /help for the list.
  • Natural language: any other line is planned by Fast-Brain into warden tool
    calls, each confirmed before it runs.


Guided argument forms: when a `/` command needs more than you typed, warden
collects the arguments interactively — a numbered pick-list for fields with a
known set (model, permission_mode, type, yes/no), free text for the rest. A
command auto-opens the form when a required argument is missing (e.g. bare
/spawn); add a trailing + to fill every field (/spawn+ <prompt>). Each field opens with a suggested value you can accept with Enter,
type over, or clear with "-".


`!cmd` runs a command in your own $SHELL. Natural language runs on
Fast-Brain (headless backend CLI, no local model or config needed); the
`/` commands and `!cmd` keep working if it is unavailable.


Usage:
  warden backend repl [flags]


Flags:
  -h, --help   help for repl


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden usage

Section titled “warden usage”
Show provider usage for subscription backends


Usage:
  warden usage [flags]


Commands:
  spend                Show measured Claude spend in dollars, per agent / repo / day
  savings              Show the token reductions warden's lifecycle features have earned
  insights             Mine agent history for patterns and parallelization suggestions
  recover              Fetch fresh usage and reconcile exhausted buckets to affected agents


Flags:
  -h, --help      help for usage
      --json      print the stable JSON document
      --refresh   bypass the daemon's fresh usage cache


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden usage spend

Section titled “warden usage spend”
Report the measured Claude spend warden read from agents' transcripts — the exact input/output tokens each agent sent and received — priced per model into estimated dollar figures and rolled up per-agent, per-repo, and per-day. Token counts are exact (read directly from the transcript); dollar figures are estimates based on published list prices (as of 2026-06) and exclude prompt-cache tokens and any volume/batch/enterprise discounts, so they may differ from your actual bill. The headline names the daily and weekly totals the budget gate (budget_gate / budget_daily_usd / budget_weekly_usd) enforces. This is the cost side of warden's savings ledger: where `wd savings` reports what warden kept OUT of context, `wd usage spend` reports what agents actually billed. Gated by the `savings` config setting.


Usage:
  warden usage spend [flags]


Flags:
      --by string   show only one rollup: agent, repo, or day (default: all three)
  -h, --help        help for spend
      --json        output the structured rollup as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden usage savings

Section titled “warden usage savings”
Report the measured token savings warden has recorded — the raw output its lifecycle features (starting with `wd check`) kept out of agents' context windows — as a per-feature breakdown with cumulative tokens, an estimated dollar figure, and the percentage of would-be context spend eliminated. Token counts are exact (a real, append-only ledger — a proof point you can screenshot); dollar figures are estimates based on published list prices (as of 2026-06) and exclude prompt-cache tokens and any volume/batch/enterprise discounts, so they may differ from your actual bill. Gated by the `savings` config setting.


Usage:
  warden usage savings [flags]


Flags:
      --audit               print a few retained raw-vs-kept provenance samples (requires savings_samples) so real bytes behind the counts can be eyeballed
      --benchmark           show the headline A/B proof (without-vs-with-warden tokens, reduction %, $ saved) with a per-day trend sparkline, instead of the per-feature table
      --calibrate           measure this workload's true bytes-per-token ratio against Claude's count_tokens endpoint (needs ANTHROPIC_API_KEY and retained samples) and persist it, so figures stop relying on the generic 4-bytes/token guess
      --calibrate-max int   cap the number of paid count_tokens calls a --calibrate run makes (default 50)
  -h, --help                help for savings
      --json                output the structured summary as JSON
      --since string        only count savings since this window (24h, 7d, 2w) or date (2006-01-02 / RFC3339)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden usage insights

Section titled “warden usage insights”
Analyze warden's own history — completed and active agent sessions plus recorded resource metrics — into actionable suggestions: typical/outlier durations by type, frequently co-edited files, error rates, busy periods, and sequential-but-disjoint sessions that could have run in parallel. Deterministic.


Usage:
  warden usage insights [flags]


Flags:
  -h, --help             help for insights
      --json             output the structured report as JSON
      --limit int        cap the number of archived sessions mined (0 = daemon default)
      --session string   scope parallelization suggestions to one session (by id or name)
      --since string     only mine sessions since this window (24h, 7d, 2w) or date (2006-01-02 / RFC3339)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden usage recover

Section titled “warden usage recover”
Operator-triggered one-shot usage reconciliation.


Fetches fresh supported provider usage snapshots (never treats cached/stale data
as forced exhaustion), calculates bucket-to-agent impact, and — unless
--dry-run — invokes the same backend recovery coordinator path as the
background usage reconciliation loop.


Default invocation is an explicit operator action and may start recovery for
affected agents. Use --dry-run to print snapshots, impact, and candidate
decisions without claiming fences or starting recovery.


Optional --ai-cli and --project filters limit which agents may be affected;
unrelated agents are left untouched. --max-parallel-swaps temporarily overrides
the coordinator's bounded concurrency for this invocation only.


Usage:
  warden usage recover [flags]


Flags:
      --ai-cli string            limit reconciliation to agents on this AI CLI / provider
      --dry-run                  fetch fresh snapshots and calculate impact without starting recovery
  -h, --help                     help for recover
      --json                     print the structured recover response as JSON
      --max-parallel-swaps int   temporary bounded concurrency override for this invocation (0 = daemon default)
      --project string           limit reconciliation to agents in this project path


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden config

Section titled “warden config”
Print the live, resolved configuration values warden is using, grouped by area,
with the config file path at the top. Edit the file by hand to change settings.


Settings are organized into namespaced blocks in the config file:
  rails.*    — guard/hook settings (git_redirect, root_guard, isolation_guard, …)
  tokens.*   — token-guard, budget-gate, and savings settings
  notify.*   — desktop notification and webhook settings
  worktree.* — worktree-retention and spawn-gate settings
  local_llm.*— DEPRECATED (Fast-Brain replaced the local model); still parsed, ignored


Deprecated flat keys (e.g. token_guard, notify, local_llm_url) still load
and are automatically migrated to the namespaced form on `warden config init`.


Usage:
  warden config [flags]


Commands:
  path                 Print the resolved config file path
  init                 Create the config file (or migrate it, adding any missing keys and upgrading deprecated flat keys to namespaced blocks)


Flags:
  -h, --help   help for config


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden config path

Section titled “warden config path”
Print the resolved config file path


Usage:
  warden config path [flags]


Flags:
  -h, --help   help for path


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden config init

Section titled “warden config init”
Create the config file (or migrate it, adding any missing keys and upgrading deprecated flat keys to namespaced blocks)


Usage:
  warden config init [flags]


Flags:
  -h, --help   help for init


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden daemon

Section titled “warden daemon”
Run the warden hub (HTTP API + poller; the single writer to the file store)


Usage:
  warden daemon [flags]


Commands:
  mcp                  Run the MCP stdio server so an orchestrator Claude can manage agents
  token                Manage the daemon's remote-access bearer token


Flags:
  -h, --help                help for daemon
      --log-format string   log output format: text | json (overrides log.format config)
      --log-level string    log verbosity: debug | info | warn | error (overrides log.level config)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden daemon mcp

Section titled “warden daemon mcp”
Run the MCP stdio server so an orchestrator Claude can manage agents


Usage:
  warden daemon mcp [flags]


Flags:
  -h, --help   help for mcp


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden daemon token

Section titled “warden daemon token”
Manage the daemon's remote-access bearer token


Usage:
  warden daemon token [flags]


Commands:
  generate             Generate a random bearer token for remote (non-loopback) access
  show                 Print the current bearer token (for pasting into a remote client)
  rotate               Generate a new bearer token, persist it, and restart the daemon


Flags:
  -h, --help   help for token


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden daemon token generate

Section titled “warden daemon token generate”
Generate a cryptographically random 256-bit bearer token and print it to stdout.


warden does not store the token. Export it so the daemon picks it up:


  export WARDEN_TOKEN=$(warden daemon token generate)


The token is required before the daemon will bind to a non-loopback address.
Treat it like a password.


To mint a read-only token, generate one and export it as WARDEN_READONLY_TOKEN:


  export WARDEN_READONLY_TOKEN=$(warden daemon token generate)


A read-only token may read everything (all GETs plus the live event stream) but
is denied every state-changing action and the interactive attach. It only works
alongside a primary WARDEN_TOKEN; the daemon refuses to start with a read-only
token but no primary token. (The token value is identical either way — what makes
it read-only is the env var you assign it to.)


Usage:
  warden daemon token generate [flags]


Flags:
  -h, --help   help for generate


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden daemon token show

Section titled “warden daemon token show”
Print the bearer token local clients resolve: WARDEN_TOKEN if exported,
otherwise the token a managed install persists in ~/.warden/token.env.


Use this to retrieve the secret to paste into the mobile web dashboard. The token
is printed to stdout (so it pipes cleanly); its source is noted on stderr.


With --readonly, print the read-only token instead (WARDEN_READONLY_TOKEN if
exported, otherwise its line in the token file).


Usage:
  warden daemon token show [flags]


Flags:
  -h, --help       help for show
      --readonly   print the read-only token (WARDEN_READONLY_TOKEN) instead of the primary


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden daemon token rotate

Section titled “warden daemon token rotate”
Rotate the daemon's bearer token: generate a fresh 256-bit secret, write it to
~/.warden/token.env (chmod 600), and restart the managed warden service so
the new token takes effect immediately. The new token is printed to stdout.


After rotating, update remote clients (paste the new token into the mobile
dashboard) and re-export WARDEN_TOKEN in any shell that held the old value.


Use --no-restart to write the new token without restarting; you must then restart
the daemon yourself before the new token is honored.


Usage:
  warden daemon token rotate [flags]


Flags:
  -h, --help         help for rotate
      --no-restart   write the new token without restarting the daemon


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden completion

Section titled “warden completion”
Generate shell completion scripts for warden.


The completion script for each shell should be redirected to the appropriate
location for your shell. Examples:


Bash:
  warden completion bash > /etc/bash_completion.d/warden
  # or for user-only installation:
  warden completion bash > ~/.bash_completion


Zsh:
  warden completion zsh > /usr/local/share/zsh/site-functions/_warden
  # or for user-only installation:
  warden completion zsh > ~/.zsh/completion/_warden


Fish:
  warden completion fish > ~/.config/fish/completions/warden.fish


PowerShell:
  warden completion powershell > warden.ps1
  # Then load it in your PowerShell profile


After generating the completion script, you may need to restart your shell
or source the file for the completions to take effect.




Usage:
  warden completion [flags]


Commands:
  bash                 Generate bash completion script
  zsh                  Generate zsh completion script
  fish                 Generate fish completion script
  powershell           Generate PowerShell completion script


Flags:
  -h, --help   help for completion


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden completion bash

Section titled “warden completion bash”
Generate bash completion script


Usage:
  warden completion bash [flags]


Flags:
  -h, --help   help for bash


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden completion zsh

Section titled “warden completion zsh”
Generate zsh completion script


Usage:
  warden completion zsh [flags]


Flags:
  -h, --help   help for zsh


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden completion fish

Section titled “warden completion fish”
Generate fish completion script


Usage:
  warden completion fish [flags]


Flags:
  -h, --help   help for fish


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden completion powershell

Section titled “warden completion powershell”
Generate PowerShell completion script


Usage:
  warden completion powershell [flags]


Flags:
  -h, --help   help for powershell


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden factory-reset

Section titled “warden factory-reset”
Reset warden's persisted state toward a clean new install.


This is destructive. Always stop the daemon before the offline wipe phase — the
session store lock is held while the hub is running.


Phases:
  1. Drain (when the daemon is reachable): terminate agents, cancel pipelines,
     stop autopilot runs, delete schedules.
  2. Offline wipe: remove on-disk stores for the selected scope.


Scopes:
  runtime  — live fleet + coordination scratch (active agents, pipelines,
             context, inbox, prompts/hints/settings/exits). Keeps archived
             history, projects, backends, metrics, and config.
  data     — every daemon store under data_dir (default). Keeps config.yaml,
             presets, prompt templates, and token unless you choose full.
  full     — data scope plus fresh config.yaml (unless --keep-config),
             presets, prompt templates, token, REPL history, and tutorial marker.


Examples:
  warden factory-reset --scope data --backup ~/.warden.bak --yes
  warden factory-reset --scope full --yes
  warden factory-reset --scope runtime --prune-worktrees --yes


Usage:
  warden factory-reset [flags]


Flags:
      --backup string     copy data_dir here before wiping (must not exist)
  -h, --help              help for factory-reset
      --keep-backends     keep the backend registry (tiers/models) for data/full scopes
      --keep-config       with --scope full, keep config.yaml instead of rewriting defaults
      --prune-worktrees   during drain, remove agent worktrees and prune orphans per repo
      --scope string      reset scope: runtime, data, or full (default "data")
      --skip-drain        skip the live drain phase (daemon may be down; wipe still requires it stopped)
      --yes               confirm the destructive reset without prompting


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden bug-report

Section titled “warden bug-report”
Show the sanitized crash draft warden staged under ~/.warden/crashes/<id>.json
(title, environment, sanitized stack) and ask whether to submit it to
https://github.com/srjn45/warden/issues. The default answer is N: nothing is
ever uploaded unless you type y.


On approval, an authenticated gh CLI creates the issue and its URL is printed;
otherwise a pre-filled new-issue link is printed for you to open. Declining
leaves the draft staged.


With no id, lists the staged drafts, newest first. Agents must never answer y
on the operator's behalf — tell the user to run this command instead.


Usage:
  warden bug-report [id] [flags]


Flags:
  -h, --help   help for bug-report
      --json   emit the outcome as JSON (never submits; prints the preview only)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden login

Section titled “warden login”
Authenticate this node with a warden-hub relay using the device flow.


The node generates an ECDSA keypair locally and initiates device authorization with
the hub. You will receive a verification URL and user code to approve in your browser.
Once approved, the signed node certificate and CA chain are stored locally in
~/.warden/identity. The private key never leaves this machine.


Usage:
  warden login [flags]


Flags:
  -h, --help              help for login
      --hostname string   display hostname override for this node
      --hub string        warden-hub base URL (default http://localhost:9876)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden setup

Section titled “warden setup”
Verify the current install with the same checks as `warden doctor`, then
install whatever is missing. setup is idempotent: it only touches deps that
are not already on PATH.


For each missing dependency it prints the exact install command and prompts
before running it (use --yes for non-interactive/automation). Required deps
(tmux, git, claude) are offered first, then optional ones (gh).


Package managers: Homebrew on macOS (never auto-bootstrapped — if brew is
missing setup prints the instruction and skips brew installs), and apt, dnf,
or pacman on Linux (auto-detected). Claude Code uses its official
installers. After installing, setup re-runs the checks and prints the report.


setup is CLI-only by design (it installs host packages) and is not exposed
over MCP or the daemon.


Usage:
  warden setup [flags]


Flags:
  -h, --help   help for setup
      --yes    install all missing dependencies without prompting (non-interactive)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden init

Section titled “warden init”
Initialize the Warden data directory (~/.warden) and schema ledger.


On a fresh install, builds the data directory by running the migration chain from schema 0
and records the initial schema ledger (schema.json). On an existing installation without a ledger,
infers and stamps the baseline ledger from existing sentinel files. If migrations are pending,
applies them to bring the data directory up to the binary's schema version.


Upgrade and fresh install share the same migration code path.


Usage:
  warden init [flags]


Flags:
      --data-dir string   data directory (default from config: ~/.warden)
  -h, --help              help for init
      --json              print machine-readable JSON output


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden tutorial

Section titled “warden tutorial”
A friendly, idempotent tour of warden: spawn → watch → talk → tear down, plus
the TUI and web GUI. Completing it (or --skip) writes a tutorial-complete marker
in your data_dir so the first-run hint stops nagging. Re-run with --reset to clear
the marker and see it fresh. Disable the hint entirely with the `tutorial` config
setting.


Usage:
  warden tutorial [flags]


Flags:
  -h, --help    help for tutorial
      --reset   delete the completion marker so the tutorial (and first-run hint) run fresh
      --skip    mark the tutorial complete without running it (silences the first-run hint)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden doctor

Section titled “warden doctor”
Run preflight checks (required binaries, daemon, data dir, agent store, backend registry integrity)


Usage:
  warden doctor [flags]


Flags:
  -h, --help                   help for doctor
      --reconcile-membership   backfill missing project_id and rebuild project membership lists offline (daemon must be stopped)
      --sessions               diagnose the session store offline without modifying it


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden tui

Section titled “warden tui”
Live terminal cockpit for agents


Usage:
  warden tui [flags]


Flags:
  -h, --help                  help for tui
      --rebuild-web-cockpit   kill and rebuild the daemon-owned web cockpit tmux session (the browser /tui view), then exit — an escape hatch for a wedged web cockpit
      --tmux-native           lay the cockpit out as a native tmux window in the current session instead of a nested tmux (auto-enabled when launched inside tmux; requires $TMUX)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden update

Section titled “warden update”
Download a verified GitHub release archive, atomically replace
~/.local/bin/warden, re-sign on macOS when the warden-codesign identity is
present, run config migrations, restart the user-level daemon service, and
wait for /healthz to report ok on the new version AND on the data schema
version the new binary writes (see "warden version").


The update is a transaction. Before any change it records the current binary,
service manager and daemon version, and verifies the backend store read-only:
an unrecoverable store stops the update with the diagnosis and repair command
instead of swapping into a daemon that cannot boot (auto-recoverable findings
are reported, not blocking). After the restart the real daemon startup error
(journal / stderr tail) is shown on failure. On ANY failure the previous binary
is restored, the service restarted, and the old version verified healthy; both
the original failure and the rollback outcome are reported.


When the new release moves the data to a newer schema (the schema-2 cutover to
the single warden-db), the daemon is stopped first, a data snapshot is taken,
and the NEW binary runs "migrate --apply" (strict preflight, an immutable
checksummed backup, staged export with count/hash/reference verification, atomic
promotion, then the ledger). The daemon is restarted only afterwards and must
report the new schema. If the migration or the restart fails, the previous
binary and data are restored (a promoted warden-db is preserved under backups/,
never deleted). Legacy stores are kept after the cutover.


Flags:
  --check            report whether an update is available without applying it
  --plan             inspect the planned upgrade path, breaking changes, downtime, and disk needed
  --yes              skip confirmation for breaking or data-touching updates
  --version <tag>    install a specific release (e.g. 9.9.0 or v9.9.0)
  --force            reinstall even when already on the target version
  --ready-timeout    overall deadline for the daemon to become healthy (default 90s)


Examples:
  warden update
  warden update --check
  warden update --plan
  warden update --version v9.9.0
  wd update --force


Usage:
  warden update [flags]


Flags:
      --check                    query and print whether an update is available without applying it
      --force                    reinstall even when already on the target version
  -h, --help                     help for update
      --plan                     inspect planned upgrade path, breaking changes, downtime, and disk needed without changing anything
      --ready-timeout duration   overall deadline for the restarted daemon to report healthy on the new version (default 1m30s)
      --version string           install a specific release tag (e.g. 9.9.0 or v9.9.0)
      --yes                      automatically confirm updates that require confirmation


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden migrate

Section titled “warden migrate”
Run data format migrations for the Warden data directory.


Actions (select one):
  --check    Read-only preflight check across all stores and pending migrations,
             including a preview of the schema-2 mapping (pipeline references,
             legacy pipelines/*.json copies, relationships) on a private copy,
             so a blocker is reported before anything is stopped
  --plan     Read-only schema-2 (warden-db) cutover plan: source/target inventory,
             strict verification of every legacy store (corruption, ambiguity,
             duplicate identities, unsupported layouts, unsafe artifacts),
             backup location and blocking conditions. Writes nothing
  --staging-export
             Export normalized schema-2 staging collections into a separate
             review directory. Reconciles pipelines-db with the legacy
             pipelines/*.json copies (identical copies dedupe, deleted pipelines
             are not resurrected and keep a historical_pipeline provenance on
             archived agents/plans; conflicts, unproven deletions and live
             records of a missing pipeline refuse). Refuses relationship
             violations and divergent existing staging records. Never writes
             legacy sources or schema.json
  --apply    Apply pending migrations up to the target schema version. For a
             schema-1 data dir this is the schema-2 cutover to the single
             warden-db: the daemon must be stopped; strict preflight, then an
             immutable checksummed backup under backups/pre-schema2-*, staging
             export, counts/hash/reference verification, atomic promotion, and
             only then the ledger moves to schema 2. Legacy stores are kept
             (nothing is deleted). Any refusal before promotion leaves the data
             exactly as it was
  --retirement
             Read-only legacy-store retirement entry-criteria report: schema-2
             active, warden-db present, backup verified, migration succeeded,
             no unresolved failures or rollbacks, zero legacy opens, runtime
             observed, support window elapsed. Deletes nothing
  --cleanup-legacy
             Explicit, backup-gated removal of the retained schema-1 stores. Re-runs
             the --retirement gate, verifies warden-db and re-verifies the cutover
             backup against its MANIFEST, lists the exact paths, asks for
             confirmation (or --yes), then MOVES them to
             backups/legacy-quarantine-<time>/ (never deletes) and records an audit
             event. --dry-run only reports. Refuses on any unmet criterion;
             re-running when nothing remains is a no-op. Recover by moving paths
             back from the quarantine or restoring the pre-schema2 backup
  --resume   Resume an interrupted migration recorded in the ledger journal
  --restore  Restore from pre-migration snapshot after an interrupted migration
             (a promoted warden-db is preserved under backups/, never deleted)


Older binaries refuse a schema-2 data dir before opening any store; there is no
automatic downgrade. "wd update" runs the cutover for you (via the new binary)
and rolls the binary and data back if it fails.


Usage:
  warden migrate [flags]


Flags:
      --apply                apply pending migrations up to the target schema version
      --check                run read-only preflight check across all stores and pending migrations
      --cleanup-legacy       move retired schema-1 stores to a quarantine dir after verifying warden-db and the cutover backup (needs confirmation)
      --data-dir string      path to the Warden data directory
      --dry-run              with --cleanup-legacy: report what would move; change nothing
  -h, --help                 help for migrate
      --json                 output results in JSON format
      --plan                 show the read-only schema-2 (warden-db) cutover plan and what blocks it
      --restore              restore from pre-migration snapshot after an interrupted migration
      --resume               resume an interrupted migration
      --retirement           report legacy-store retirement entry criteria (read-only; deletes nothing)
      --staging-dir string   target directory for --staging-export (default: <data-dir>/warden-db-staging)
      --staging-export       export normalized schema-2 staging collections without touching legacy sources
      --target int           target schema version to migrate to (default 2)
      --yes                  with --cleanup-legacy: confirm without prompting


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden rollback

Section titled “warden rollback”
Roll back the most recent warden update.


Restores the previous binary (.bak). If no schema change happened it is a
plain binary swap. Otherwise it restores the pre-update snapshot and warns
that changes made since the update are lost, requiring confirmation (--yes
to skip confirmation).


Usage:
  warden rollback [flags]


Flags:
  -h, --help                     help for rollback
      --json                     output result as JSON
      --ready-timeout duration   overall deadline for the restored daemon to report healthy (default 1m30s)
  -y, --yes                      skip loss-of-changes confirmation prompt


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden version

Section titled “warden version”
Print warden version and build information


Usage:
  warden version [flags]


Flags:
  -h, --help   help for version
      --json   output build info as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden start

Section titled “warden start”
Spawn an agent. --role is required (see 'warden agent role list'); there is no
implicit fallback role.


Spawn modes:
  Free-form    warden agent start --role <ROLE> "<prompt>" [--dir <path>]
               Autonomous: runs the prompt in --dir (default: current directory).
  Interactive  warden agent start --role <ROLE> --dir <path>
               No prompt: opens the agent and waits for you.
  Managed      warden agent start --role worker --repo <PATH> [TICKET]
               Isolated git worktree off --repo (worker role + --repo).
  Terminal     warden agent start --kind terminal --dir <path>
               Not an AI agent: a plain shell ($SHELL) in --dir, with the same
               worktree/git/tmux lifecycle. --aicli/--model/--role/prompt are ignored.


Which AI CLI + model runs (first match wins):
  1. --aicli + --model         explicit pin (--model requires --aicli)
  2. --aicli alone             optimal model for that AI CLI at the tier
  3. --tier (or --task)        quota-balanced resolver at that tier
  4. --role alone              resolver routed by the role's tier
  5. configured defaults
So --role on its own is always enough; --tier/--aicli/--model only refine it.


Accepted --aicli values: claude (default), aider, opencode, codex, crush, goose,
cursor, antigravity. Per-AI-CLI behaviour (model, resume, spend fidelity) and
maturity labels: see 'warden backend --help'.


Usage:
  warden start --role <ROLE> [TICKET|"<prompt>"] [--repo <PATH>] [--dir <PATH>] [--aicli <ID>] [flags]


Flags:
      --aicli <ID>                  AI CLI <ID>: claude (default, stable) | aider | opencode | codex | crush | goose | cursor | antigravity — only claude is fully tested; codex/antigravity are beta, the rest experimental. See 'warden backend --help' for per-AI-CLI notes
      --auto-restart                auto-resume this agent if it crashes (errored), capped at a few attempts
      --branch string               new branch (development) or checkout target (pr-review)
      --dir string                  directory to launch the agent from (default: current directory)
      --force                       spawn even when the memory-pressure gate warns
      --fork-from <AGENT>           fork the existing agent <AGENT>'s recorded session into this new managed agent (codex's native fork): branches the source's conversation in a fresh sibling worktree off its branch, carrying its uncommitted tracked changes; the source keeps running. Uses --role worker when the chosen role does not own a worktree; the fork inherits the source's repo+backend. See 'warden agent fork' for the shorthand
  -h, --help                        help for start
      --in-repo                     managed spawns only: opt out of isolation and run in the shared --repo checkout instead of a worktree (ignored for pr-review; overridden when root_guard is on)
      --json                        emit the new agent (id, name, role, ai_cli, model, workdir) as JSON
      --kind string                 session kind: empty/agent (default) spawns an AI agent; terminal opens a plain interactive shell ($SHELL) in --dir (not an AI agent — --aicli/--model/--role/prompt ignored)
      --model string                model ID for the chosen AI CLI (requires --aicli). Empty lets the tier resolver pick an explicit model
      --name string                 explicit agent name (omit to auto-resolve); max 32 chars, alphanumeric + hyphens/underscores
      --permission-mode string      permission mode: acceptEdits|auto|bypassPermissions|default|dontAsk|plan (default: from config or 'auto')
      --permission-posture string   Warden prompt authority: read-only|read-write|allowlisted|dangerously-execute-all (default: role/config/legacy-mode mapping)
      --plan string                 optional planstore plan id in the same project (plan-<8hex>); empty = planless agent. A non-empty value must name an existing plan belonging to the resolved project
      --pr string                   PR number/url (pr-review)
      --preset <NAME>               load saved spawn defaults from the named preset <NAME> (see 'warden project preset'); explicit flags override
      --project <ID>                <ID> of the daemon project this agent joins (its canonical path or remote URL, from 'warden projects list'); stamps membership explicitly instead of leaving the daemon to path-match the launch dir. Empty = the git repository root of the launch directory (the daemon auto-registers it)
      --prompt-template <NAME>      fill the saved prompt template <NAME> (see 'warden project prompt-template') as the spawn prompt; a positional prompt still wins
      --repo string                 repo path for a managed spawn: with --role worker, picks an isolated worktree off this repo (the default managed mode; branch it with --branch). Empty = free-form unless --fork-from forces managed (then defaults to cwd)
      --role <ROLE>                 REQUIRED — built-in agent role <ROLE>: general | autopilot | brain | orchestrator | planner | worker (legacy aliases implementer/auto-merger/reviewer resolve to worker). Injects the role's persona as a system-prompt addendum and applies its default flags. See 'warden agent role list'
      --set stringArray             supply a prompt-template variable as VAR=value (repeatable, e.g. --set FILE=foo.go --set X=y)
      --tags <LIST>                 comma-separated labels <LIST> for grouping/filtering (e.g. --tags backend,urgent); searchable and filterable via 'warden agent list --tag'
      --task string                 task name (task registry) used to derive the model tier when --tier is empty. Empty = none
      --tier string                 model tier for the quota-balanced resolver that picks the AI CLI+model: tier-1|tier-2|tier-3. Empty derives the tier from --task, then --role (--role is required, so this always has a role to derive from). An explicit --aicli/--model still wins over the resolver
      --worktree                    managed spawns only: use a throwaway scratch worktree instead of a branch worktree (analysis/spike). Neither --worktree nor --in-repo = the normal isolated branch worktree


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden ls

Section titled “warden ls”
List all active agent sessions


Usage:
  warden ls [flags]


Flags:
  -a, --all           include system agents
  -h, --help          help for ls
      --json          output as JSON
      --tag strings   only show agents carrying every given tag (repeatable or comma-separated, e.g. --tag backend --tag urgent)
  -w, --watch         live-update the list on every agent state change (Ctrl+C to exit)


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden status

Section titled “warden status”
Show full status for one session


Usage:
  warden status <AGENT> [flags]


Flags:
  -h, --help   help for status
      --json   output as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden send

Section titled “warden send”
Type a message into an agent's AI CLI session and press Enter


Usage:
  warden send <AGENT> <message...> [flags]


Flags:
  -h, --help   help for send


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden commit

Section titled “warden commit”
Stage and commit every change in the current worktree on its branch.


warden refuses protected branches (main/master), runs pre-commit hooks and
returns only failures, and links the commit to this agent — one call in place
of the git status/add/commit/rev-parse round-trips.


Pass -m to author the message (best — you made the change). Omit it and warden
writes one: the local model from the staged diff if configured, otherwise a
deterministic conventional-commit message from the changed paths.


Give paths (relative to the current directory) to stage and commit only those;
paths outside the repository are rejected. With no paths everything is staged.


--amend rewrites the last commit, keeping its message unless -m is given. It is
refused on a merge commit and on a commit already in the upstream branch unless
--force (after which push needs --force-with-lease).


Usage:
  warden commit [paths...] [flags]


Flags:
      --amend            rewrite the last commit (keeps its message unless -m is given)
      --force            with --amend, allow amending a commit already in the upstream branch
  -h, --help             help for commit
      --json             emit the raw result as JSON
  -m, --message string   commit message; if omitted, warden generates one from the diff


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden push

Section titled “warden push”
Push the current worktree branch to origin, setting upstream.


warden refuses to push protected branches (main/master) directly — push your
agent branch and open a PR.


Pass --force-with-lease after a rebase or amend to overwrite your remote
branch. warden only ever uses --force-with-lease (never a bare --force), so
the push aborts if a teammate pushed to your branch since your last fetch.


Usage:
  warden push [flags]


Flags:
      --force-with-lease   push with --force-with-lease (safe force after a rebase/amend)
  -h, --help               help for push
      --json               emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden sync

Section titled “warden sync”
Fetch origin and rebase the current branch onto origin/<base> (default main).


Refuses a dirty tree (commit first). On conflict warden leaves the rebase in
progress and reports only the conflicting files for you to resolve.


While a rebase is in progress, `wd sync --continue` stages your resolved files and
finishes it (reporting any conflicts from the next commit), and `wd sync --abort`
drops it and restores the branch. A plain sync or `wd commit` is refused until then.


Exits non-zero when the rebase stops on conflicts.


Usage:
  warden sync [flags]


Flags:
      --abort         drop a rebase in progress and restore the branch
      --base string   base branch to rebase onto (default main)
      --continue      finish a conflicted rebase: stage resolved files and run git rebase --continue
  -h, --help          help for sync
      --json          emit the raw result as JSON


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

warden release

Section titled “warden release”
Inspect commits since the latest SemVer tag and recommend the next release:
the bump (major/minor/patch), the next vMAJOR.MINOR.PATCH, and a categorized
changelog built from conventional commits and merged PRs.
A squash commit whose subject is not itself releasable (e.g. "autopilot: x (#1)")
is bumped by the conventional "* feat(...): ..." bullets in its body.


By default, the analysis targets origin/main (or origin/master) so releases are
evaluated against canonical upstream commits rather than uncommitted local edits
or active feature/agent worktrees. Pass --target to override.


This is the step after the final PR of a plan is merged.


Unless --no-fetch is given, the command fetches the target ref from origin first.


Interactive by default: asks before creating an annotated tag directly on the
target commit (default N), then — only if --push was given — asks before pushing
it to origin (default N). The tag message carries the rendered changelog. An
existing tag is never overwritten.


  --target <ref> set target ref to release (default: origin/main or origin/master)
  --no-fetch     skip fetching the target ref from origin before analysis
  --dry-run      print the recommendation only; never tag or push
  --yes          skip the create-tag prompt and create the annotated tag
  --push         push the tag to origin after it exists (prompts unless --yes)
  --yes --push   tag and push with no prompts
  --json         emit the advice and the actions taken as JSON


Agents should run `wd release --dry-run`; pass --yes only when the operator
explicitly asked for a tag. Pushing a v* tag triggers the release pipeline.


Usage:
  warden release [flags]


Flags:
      --dry-run         print the recommendation only; never tag or push
  -h, --help            help for release
      --json            emit the advice and actions taken as JSON
      --no-fetch        skip fetching target ref from origin before analysis
      --push            push the tag to origin after creating it (prompts unless --yes)
      --target string   target ref or branch to release (default: origin/main or origin/master)
      --yes             skip the create-tag prompt and create the annotated tag


Inherited flags:
      --addr string     daemon address (overrides the addr config setting)
      --config string   config file path (default ~/.warden/config.yaml)

Compatibility aliases

Section titled “Compatibility aliases”

Every path below predates the command redesign and still runs, dispatching the same option parsing and run logic as its canonical path. They are hidden from normal help and completion; warden help --all lists the same set. Nothing here is scheduled for removal — prefer the canonical path in new scripts and docs.

Legacy pathCanonical path
warden adoptwarden agent adopt
warden agent compactwarden agent set
warden agent compact setwarden agent set
warden agent permission-modewarden agent set
warden agent permission-mode setwarden agent set
warden agent role setwarden agent set
warden agent role set-tierwarden agent role tier set
warden agent role tier lswarden agent role tier list
warden approvalswarden approval list
warden approvewarden approval answer
warden attachwarden agent attach
warden auditwarden inspect audit
warden audit logwarden inspect audit
warden auto-approvewarden approval auto set
warden auto-approve allowwarden approval auto allow
warden auto-approve clearwarden approval auto clear
warden auto-approve denywarden approval auto deny
warden auto-approve disablewarden approval auto disable
warden auto-approve enablewarden approval auto enable
warden auto-approve policywarden approval auto rules
warden auto-approve ruleswarden approval auto rules
warden auto-approve showwarden approval auto rules
warden backend lswarden backend list
warden backend model lswarden backend model list
warden backendswarden backend
warden backends defaultwarden backend default
warden backends disablewarden backend disable
warden backends enablewarden backend enable
warden backends listwarden backend list
warden backends lswarden backend list
warden backends rescanwarden backend rescan
warden backends tierwarden backend tier
warden brancheswarden workspace branches
warden check lswarden check list
warden cleanwarden workspace clean
warden collabwarden workspace
warden collab conflictswarden workspace conflicts
warden collab who-is-editingwarden workspace who-is-editing
warden costretained; no canonical equivalent
warden cost savingswarden usage savings
warden cost spendwarden usage spend
warden ctxwarden context
warden ctx appendwarden context append
warden ctx caswarden context cas
warden ctx delwarden context delete
warden ctx getwarden context get
warden ctx listwarden context list
warden ctx setwarden context set
warden deletewarden agent delete
warden digestwarden agent digest
warden donewarden agent done
warden exportwarden inspect export
warden force-compactwarden agent set
warden forkwarden agent fork
warden handoffwarden agent handoff
warden historywarden inspect history
warden hook check-guardwarden check guard
warden hook git-guardwarden git guard
warden hook guardwarden check boundary
warden hook root-guardwarden check root-guard
warden iwarden backend repl
warden importwarden inspect import
warden insightswarden usage insights
warden interactivewarden backend repl
warden libwarden project library
warden librarywarden project library
warden library listwarden project library list
warden library save-presetwarden project preset save
warden library save-promptwarden project prompt-template save
warden llmwarden backend suggest
warden llm suggestwarden backend suggest
warden mcpwarden daemon mcp
warden memorywarden project memory
warden modelswarden backend model
warden models addwarden backend model add
warden models discoverwarden backend model discover
warden models historywarden backend model history
warden models listwarden backend model list
warden models lswarden backend model list
warden models refreshwarden backend model refresh
warden models rollbackwarden backend model rollback
warden models tierwarden backend model tier
warden msgwarden message
warden msg inboxwarden message inbox
warden msg sendwarden message send
warden msg waitwarden message wait
warden pipeline lswarden pipeline list
warden plan lswarden plan list
warden pluginwarden project plugin
warden plugin listwarden project plugin list
warden presetwarden project preset
warden preset listwarden project preset list
warden preset savewarden project preset save
warden project library save-presetwarden project preset save
warden project library save-promptwarden project prompt-template save
warden project-groups lswarden project-groups list
warden projects lswarden projects list
warden prompt-templatewarden project prompt-template
warden prompt-template listwarden project prompt-template list
warden prompt-template savewarden project prompt-template save
warden prompt-templateswarden project prompt-template
warden prunewarden workspace prune
warden ptwarden project prompt-template
warden recoverwarden agent recover
warden remove-worktreewarden agent remove-worktree
warden repairwarden inspect repair
warden repair agentswarden inspect repair agents
warden repair allwarden inspect repair all
warden repair backendswarden inspect repair backends
warden repair sessionswarden inspect repair sessions
warden repair warden-dbwarden inspect repair warden-db
warden replwarden backend repl
warden restorewarden agent restore
warden rolewarden agent role
warden role listwarden agent role list
warden role set-tierwarden agent role tier set
warden role tierwarden agent role tier
warden role tier listwarden agent role tier list
warden role tier lswarden agent role tier list
warden role tier setwarden agent role tier set
warden rotatewarden agent rotate
warden savingswarden usage savings
warden schedule lswarden schedule list
warden schedule rmwarden schedule delete
warden searchwarden inspect search
warden set-permission-modewarden agent set
warden set-permission-posturewarden agent set
warden set-rolewarden agent set
warden snapshotwarden workspace snapshot
warden snapshot createwarden workspace snapshot create
warden snapshot listwarden workspace snapshot list
warden snapshot restorewarden workspace snapshot restore
warden spendwarden usage spend
warden statswarden inspect resources
warden stopwarden agent stop
warden switchwarden agent switch
warden tailwarden agent tail
warden terminatewarden agent terminate
warden tokenwarden daemon token
warden token generatewarden daemon token generate
warden token rotatewarden daemon token rotate
warden token showwarden daemon token show
warden worktreewarden workspace
warden worktree listwarden workspace list
warden worktree lswarden workspace list
warden worktree prunewarden workspace prune