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

spawn, monitor, and tear down Claude Code 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
  autopilot            Turn autopilot mode on/off per repo and show its status
  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
  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)

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, ollama)
  tutorial             Run the first-run guided walkthrough of warden's core loop
  doctor               Run preflight checks (required binaries, daemon, data dir, configured local model)
  tui                  Live terminal cockpit for agents
  version              Print warden version and build information

Shortcuts:
  start                Spawn an agent — `start --role <ROLE> "<prompt>"` (auto-typed), `start --role <ROLE> --dir <path>` (interactive: open Claude & wait), or `start --role <ROLE> TICKET --type <TYPE>` (managed worktree)
  ls                   List all active agent sessions
  status               Show full status for one session
  send                 Type a message into an agent's claude 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)

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

warden agent

Create, inspect, communicate with, and manage agents.

Lifecycle commands deliberately remain distinct: terminate keeps the record and
worktree; done clears the record but keeps the worktree; delete changes only the
record; remove-worktree changes only the worktree; and stop composes teardown
steps according to its keep flags and preserves its confirmation safeguards.

Usage:
  warden agent [flags]

Commands:
  list                 List all active agent sessions
  start                Spawn an agent — `start --role <ROLE> "<prompt>"` (auto-typed), `start --role <ROLE> --dir <path>` (interactive: open Claude & wait), or `start --role <ROLE> TICKET --type <TYPE>` (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 (claude --resume)
  recover              Revive archived agent records whose tmux session is still alive (dry run unless --apply)
  adopt                Register the Claude session in this directory (resume it under tmux, or register the current tmux session live)
  attach               Attach to the agent's tmux session
  stop                 Tear down an agent — the single umbrella verb (default: terminate + clear record + remove worktree)
  terminate            Stop an agent: kill its tmux+claude session (keeps the record and worktree) — alias for `stop --keep-record --keep-worktree`
  done                 Terminate an agent and clear its record (does NOT remove the worktree) — alias for `stop --keep-worktree`
  delete               Clear an agent's stored record (archives by default; --hard to purge) — alias for `stop --keep-worktree` (record only)
  remove-worktree      Remove an agent's git worktree + branch (always asks; --force overrides guards) — alias for `stop --keep-record` (worktree only)
  send                 Type a message into an agent's claude session and press Enter
  tail                 Print the recent output of an agent's claude 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 `handoff --retire`)
  switch               Hot-swap an agent session to a different backend, model, or tier mid-task
  permission-mode      Manage an agent's permission mode
  role                 Inspect warden's built-in agent roles and tier mappings
  compact              Manage an agent's force-compact override

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

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

Spawn an agent. --role is required (see 'warden role list'); there is no
implicit fallback role.

Free-form:   warden agent start --role <ROLE> "<prompt>" [--dir <path>]   (autonomous)
Interactive: warden agent start --role <ROLE> --dir <path>                (opens the agent and waits)
Managed:     warden agent start --role <ROLE> TICKET --type <TYPE>        (isolated worktree)

The spawn's backend+model is resolved (top wins): an explicit --backend/--model
pin > --tier (or --task, which derives a tier) routed through the quota-balanced
resolver > the resolver routed by --role alone > warden's configured defaults.
So --role on its own is always enough to spawn — --tier/--backend/--model are
optional refinements, not additional requirements.

Backends (--backend): warden drives Claude Code by default. Accepted values:
  claude (default, stable), aider, opencode, codex, crush, goose, cursor, antigravity.
Only claude is fully tested; codex and antigravity are beta, the rest experimental / WIP.
Terminal (--kind terminal): not an AI agent — opens a plain interactive shell ($SHELL)
in --dir, managed with the same worktree/git/tmux lifecycle as any agent. It is a
session kind, not a backend, so --backend/--model/--role/prompt are ignored.
Aider: BYO model (pass --model), no resume, runs a one-shot --message task.
OpenCode: BYO model (pass --model), structured transcript, DOES resume.
Codex: BYO provider (via ~/.codex/config.toml), DOES resume (dir-scoped).
Crush: BYO model (config-driven TUI; --model for headless), DOES resume (dir-scoped); initial prompt auto-typed post-launch.
Goose: BYO provider (GOOSE_PROVIDER/GOOSE_MODEL env), DOES resume (name-deterministic); no --model on session launch.
Cursor: hosted model catalog; pass --model to override (cursor-agent --list-models / wd models); DOES resume (dir-scoped --continue); warden owns the worktree (cursor's own -w never passed).
Antigravity: Google-hosted agy; defaults gemini-3.5-flash; pass --model (agy models / wd models); DOES resume (dir-scoped agy -c).
All non-claude backends show tokens-only spend. Claude remains full-fidelity.

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

Flags:
      --auto-restart                             auto-resume this agent if it crashes (errored), capped at a few attempts
      --backend warden start --help              agent backend: claude (default, stable) | aider | opencode | codex | crush | goose | cursor | antigravity — only claude is fully tested; codex/antigravity are beta, the rest experimental. See warden start --help for per-backend notes
      --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 codex fork                     fork an existing agent's recorded session into this new managed agent (codex codex fork): branches the source's conversation in a fresh sibling worktree off its branch, carrying its uncommitted tracked changes; the source keeps running. Defaults --type to development; the fork inherits the source's repo+backend. See `warden fork` for the shorthand
  -h, --help                                     help for start
      --in-repo                                  write-agent opt-out: run in the shared repo instead of an isolated worktree (ignored for pr-review)
      --kind string                              session kind: empty/agent (default) spawns an AI agent; terminal opens a plain interactive shell ($SHELL) in --dir (not an AI agent — --backend/--model/--role/prompt ignored)
      --model string                             claude model: opus, sonnet, haiku, fable, or full model ID (default: the model_default config setting, i.e. sonnet)
      --name string                              optional human-friendly name (max 32 chars, alphanumeric + hyphens/underscores)
      --permission-mode string                   permission mode: acceptEdits|auto|bypassPermissions|default|dontAsk|plan (default: from config or 'auto')
      --pr string                                PR number/url (pr-review)
      --preset warden preset                     load saved spawn defaults from a named preset (see warden preset); explicit flags override
      --prompt-template warden prompt-template   fill a saved prompt template (see warden prompt-template) as the spawn prompt; a positional prompt still wins
      --repo string                              repo path (default: current directory)
      --role warden role list                    REQUIRED — built-in agent role: general | 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 role list
      --set stringArray                          supply a prompt-template variable as VAR=value (repeatable, e.g. --set FILE=foo.go --set X=y)
      --supervised                               alias for --permission-mode acceptEdits (kept for backwards compatibility)
      --tags warden ls --tag                     comma-separated labels for grouping/filtering (e.g. --tags backend,urgent); searchable and filterable via warden ls --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 backend+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 --backend/--model still wins over the resolver
      --type string                              task type: development|analysis|spike|pr-review|code|docs|website|debug-ci|tests|other
      --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 agent status

Show full status for one session

Usage:
  warden agent status <TICKET> [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

Summarize what an agent accomplished (files, branch, turns, narrative)

Usage:
  warden agent digest <TICKET> [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

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 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
      --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)
      --type string              worktree-backed task type for the fork (must isolate in its own worktree) (default "development")

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

warden agent restore

Recreate and resume a lost/orphaned agent (claude --resume)

Usage:
  warden agent restore <TICKET> [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

Scans archived (closed) agent records for ones 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.

Usage:
  warden agent recover [flags]

Flags:
      --apply   actually re-insert candidates (default: report only)
  -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

Register the Claude session in this directory (resume it under tmux, or register the current tmux session live)

Usage:
  warden agent adopt [flags]

Flags:
      --dir string          directory whose claude session to adopt (default: current directory)
  -h, --help                help for adopt
      --session-id string   claude session uuid 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

Attach to the agent's tmux session

Usage:
  warden agent attach <TICKET> [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

Stop an agent. The single umbrella teardown verb.

<AGENT> is any identifier `wd ls` shows — the agent's name, its id, or its
ticket. All teardown verbs resolve by name-or-id.

By default `wd agent stop <TICKET>` does a FULL teardown: terminate the
tmux+claude session, clear (archive) the record, and remove the git worktree +
branch (asking for confirmation first, unless --yes). Subtractive flags keep
parts around; --pr opens a GitHub PR first while the agent is still intact.

The four older verbs are kept as thin aliases — each is just `stop` with a
fixed flag combo:

  old verb                    equivalent
  --------------------------  ------------------------------------------------
  wd terminate <T>            wd agent stop <T> --keep-record --keep-worktree
  wd delete <T> [--hard]      wd agent stop <T> --keep-worktree (record only)
  wd remove-worktree <T>      wd agent stop <T> --keep-record  (worktree only)
  wd done <T> [--hard|--pr]   wd agent stop <T> --keep-worktree [--hard|--pr]
  wd agent stop <T>                 terminate + clear record + remove worktree

Safe ordering is always: PR -> terminate -> clear record -> remove worktree, so
a failed push leaves the agent running.

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
      --keep-record             do not clear the stored record
      --keep-worktree           do not remove the git worktree (this + default == the old 'done')
      --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

Stop an agent: kill its tmux+claude session (keeps the record and worktree) — alias for `stop --keep-record --keep-worktree`

Usage:
  warden agent terminate <AGENT> [flags]

Flags:
  -h, --help   help for terminate

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

warden agent done

Terminate an agent and clear its record (does NOT remove the worktree) — alias for `stop --keep-worktree`

Usage:
  warden agent done <AGENT> [flags]

Flags:
      --base string   base branch for the PR (default main); only meaningful with --create-pr
      --create-pr     open a GitHub PR for the agent's branch (pushes first; title+body from the digest) before finishing
      --hard          purge the record instead of archiving
  -h, --help          help for done

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

warden agent delete

Clear an agent's stored record (archives by default; --hard to purge) — alias for `stop --keep-worktree` (record only)

Usage:
  warden agent delete <AGENT> [flags]

Flags:
      --hard   permanently purge the record instead of archiving
  -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 agent remove-worktree

Remove an agent's git worktree + branch (always asks; --force overrides guards) — alias for `stop --keep-record` (worktree only)

Usage:
  warden agent remove-worktree <AGENT> [flags]

Flags:
      --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 guards
  -h, --help                    help for remove-worktree
      --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 agent send

Type a message into an agent's claude session and press Enter

Usage:
  warden agent send <TICKET> <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

Print the recent output of an agent's claude session

Usage:
  warden agent tail <TICKET> [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

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 --confirm. This is what the `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)
      --confirm                with --retire, actually spawn the successor and retire this agent (required)
      --force                  spawn the new delegate even when the memory-pressure gate warns (ignored with --to)
  -h, --help                   help for handoff
      --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 --confirm). Equivalent to 'warden rotate'
      --to string              deliver to this existing agent id instead of spawning a new one
      --type string            task type for a new delegate (ignored with --to) (default "development")

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

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 --confirm to spawn the successor and reap this agent.

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

Usage:
  warden agent rotate [flags]

Flags:
      --confirm                actually spawn the successor and retire this agent (required for retire)
  -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

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

warden agent switch

Mid-session hot-swap: retire the active CLI process and launch a successor backend
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 --backend and/or --model, or by --tier
(resolved via quota-balanced weighted headroom routing across eligible backends).

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 --backend antigravity --model gemini-3.1-pro
  warden agent switch --tier tier-1
  warden agent switch abc123 --tier tier-3 --prompt 'Focus on unit test coverage'


Usage:
  warden agent switch [agent-id] [flags]

Flags:
  -b, --backend string   explicit successor backend id (claude, antigravity, codex, …)
  -h, --help             help for switch
      --json             emit result as JSON
  -m, --model string     explicit successor model id
  -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 to resolve tier from when --tier is not given
  -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 permission-mode

Manage an agent's permission mode

Usage:
  warden agent permission-mode [flags]

Commands:
  set                  Set the permission mode for an agent

Flags:
  -h, --help   help for permission-mode

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

warden agent permission-mode set

Set the permission mode for a specific agent.

Valid permission modes:
  acceptEdits        - Prompt for tool permissions (supervised mode)
  auto               - Default behavior
  bypassPermissions  - Skip all permission prompts
  default            - Use global default from config
  dontAsk            - Don't ask for permissions
  plan               - Plan mode

The permission mode controls how Claude handles tool permission prompts.
Setting to "default" (or empty string) clears the agent-specific override
and uses the global default_permission_mode config setting.

Examples:
  warden agent set abc123 acceptEdits  # Enable supervised mode
  warden agent set abc123 auto         # Use auto mode
  warden agent set abc123 default      # Use global default

Usage:
  warden agent permission-mode set <agent-id> <mode> [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 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
  set                  Switch an agent's built-in role (relaunches to re-inject the persona)
  set-tier             Set the default model tier for an agent role (tier-1|tier-2|tier-3)
  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

List the built-in agent roles and their descriptions

Usage:
  warden agent role 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 agent role set

Switch a running agent's built-in role.

The role's persona is injected as a system-prompt addendum; changing it relaunches
the agent (its current turn is discarded) so the new persona takes effect. Set the
role to "general" (or "") to clear the persona and behave like a plain agent.

Valid roles (see `warden role list` for descriptions):
  general | orchestrator | planner | worker
  (legacy aliases implementer/auto-merger/reviewer resolve to worker)

Examples:
  warden agent set abc123 reviewer      # give the agent the reviewer persona
  warden agent set abc123 general       # clear the persona

Usage:
  warden agent role set <agent-id> <role> [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 role set-tier

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 set-tier worker tier-2
  warden agent role set-tier orchestrator tier-1

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

Flags:
  -h, --help   help for set-tier

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

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

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

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 compact

Manage the per-agent force-compact override. Setting it may interrupt an in-flight turn when the configured context threshold is crossed.

Usage:
  warden agent compact [flags]

Commands:
  set                  Override force-compact for one agent (interrupt → /compact → resume)

Flags:
  -h, --help   help for compact

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

warden agent compact set

Set the per-agent force-compact override.

When force-compact is on and an agent's context crosses the critical threshold
while it is still working, warden interrupts the agent (Escape), runs /compact
once it goes idle, then sends the configured resume prompt so it picks its work
back up. This is destructive: the interrupt discards the agent's in-flight turn.

States:
  on       force-compact this agent (overrides the global setting)
  off      never force-compact this agent (overrides the global setting)
  inherit  clear the override; follow the global token_force_compact setting

Examples:
  warden agent set abc123 on       # always force-compact agent abc123
  warden agent set abc123 off      # never force-compact agent abc123
  warden agent set abc123 inherit  # follow the global default

The global default is the token_force_compact config setting (off by default).

Usage:
  warden agent compact set <agent-id> <on|off|inherit> [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

Define and run DAG pipelines of agent jobs.

Use validate locally before create; template list shows built-in starters;
start/pause/resume/cancel control lifecycle; show lists per-job status and handoffs.

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)
  edit-job             Edit a pending job's prompt and/or handoff
  retry                Re-run a failed or needs-attention job (reopens skipped descendants)

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

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.

Usage:
  warden pipeline validate -f <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

Create a pipeline either from a YAML spec file (-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 `warden pipeline template list` to see templates and their placeholders.

Usage:
  warden pipeline create (-f <spec.yaml> | --template <name>) [flags]

Flags:
  -f, --file string                       path to the pipeline YAML spec
  -h, --help                              help for create
      --name string                       pipeline name — fills {{NAME}} (default: the template name)
      --repo string                       repo path — fills {{REPO}} (default: the current directory)
      --set stringArray                   fill a template placeholder, KEY=VALUE (repeatable)
      --template pipeline template list   built-in template to render (see 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

Built-in pipeline templates render via create --template and support placeholder substitution.

Usage:
  warden pipeline template [flags]

Commands:
  list                 List the built-in pipeline templates and their placeholders

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

List the built-in pipeline templates and their placeholders

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 list

List pipelines

Usage:
  warden pipeline 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 show

Show a pipeline's jobs and their status

Usage:
  warden pipeline show <pipeline> [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 start

Start a pipeline (spawns jobs with no dependencies)

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

Pause a running pipeline (in-flight jobs finish; no new jobs spawn)

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

Resume a paused pipeline (spawns jobs that became ready while paused)

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

Cancel a pipeline (terminates running jobs)

Usage:
  warden pipeline cancel <pipeline> [flags]

Flags:
  -h, --help   help for cancel

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

warden pipeline delete

Delete a pipeline's record (must not have live jobs — cancel first)

Usage:
  warden pipeline delete <pipeline> [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 pipeline emit

Publish this job's handoff (run from inside a pipeline job)

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 edit-job

Edit a pending job's prompt and/or handoff

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

Flags:
      --handoff string   new handoff hint for the job
  -h, --help             help for edit-job
      --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 retry

Re-run a failed or needs-attention job (reopens skipped descendants)

Usage:
  warden pipeline 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 autopilot

Autopilot runs a long-lived headless brain agent per plan that decomposes a
goal, spawns workers, and lands green work into an integration branch
unattended. The switch is PER-REPO: `warden autopilot enable` run inside a repo
enables only that repo (others are unaffected), and the enabled set is persisted
so repos come back up across a daemon restart. The plan/manager/merge template
stays global in the `autopilot` config block. Enabling runs a preflight (plan
file valid, gh authenticated, integration branch present, at most one active run
per repo) and fails fast with the full list of problems so you fix everything in
one pass. `disable` is the kill switch. Registered runs are managed separately
under `autopilot run`. Configure the feature under the `autopilot` block in the
config file (or scaffold it with `warden autopilot init`).

Usage:
  warden autopilot [flags]

Commands:
  enable               Enable autopilot for this repo (runs the enable-time preflight)
  disable              Disable autopilot for this repo (kill switch — stops spawning/landing)
  status               Show autopilot status (which repos are enabled, and each run)
  init                 Scaffold autopilot adoption in the current repo
  register             Register a named autopilot plan
  land                 Land an autopilot worker branch into the integration branch
  run                  Manage registered autopilot runs

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 enable

Enables autopilot for the current git repository only (other repos are
unaffected). Runs the enable-time preflight and, on success, persists the repo
as enabled so it comes back up across a daemon restart. Use --repo to target a
different repository.

Usage:
  warden autopilot enable [flags]

Flags:
  -h, --help          help for enable
      --repo string   repo root to enable (default: the current git repository)

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

warden autopilot disable

Disables autopilot for the current git repository only (other enabled repos
keep running). In-flight workers are left running. Use --repo to target a
different repository.

Usage:
  warden autopilot disable [flags]

Flags:
  -h, --help          help for disable
      --repo string   repo root to disable (default: the current git repository)

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

warden autopilot status

Show autopilot status (which repos are enabled, and each run)

Usage:
  warden autopilot status [flags]

Flags:
  -h, --help   help for status

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

warden autopilot init

Creates a named template under plans/ in the current git repository (if absent),
registers it with the daemon, creates the integration branch
off the default branch if absent, and prints a CI-coverage hint when no workflow
covers integration pull requests. After init, edit the plan file and run
`warden autopilot enable` to enable.

Usage:
  warden autopilot init [flags]

Flags:
  -h, --help          help for init
      --name string   plan name (creates plans/<name>.yaml) (default "default")

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

warden autopilot register

Register a named autopilot plan

Usage:
  warden autopilot register <plan-file> [flags]

Flags:
  -h, --help          help for register
      --name string   unique run name within the repository
      --repo string   repository root (inferred from plan when omitted)

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

warden autopilot land

Merges one autopilot worker branch into the integration branch — the brain's
only merge path. Runs every precondition (owning run active, branch
autopilot-owned, a PR based on the integration branch, the resolved gate green
for the PR head, and the PR mergeable), merges with the configured strategy,
deletes the worker branch if configured, and records the landing. Idempotent:
re-issuing after a merge reports already-landed with no second merge. On a
precondition failure it prints the typed kind
(gate_pending|gate_red|ci_missing|not_mergeable|not_owned|run_disabled|wrong_base).

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

Flags:
  -h, --help   help for land

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

warden autopilot run

Start, pause, resume, stop, and unregister individual registered runs.
Distinct from repository enablement (`autopilot enable` / `autopilot disable`).

Usage:
  warden autopilot run [flags]

Commands:
  list                 List all registered autopilot runs
  start                start one autopilot run
  pause                pause one autopilot run
  resume               resume one autopilot run
  stop                 stop one autopilot run
  unregister           unregister one autopilot run

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 autopilot run list

List all registered autopilot runs

Usage:
  warden autopilot run 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 autopilot run start

start one autopilot run

Usage:
  warden autopilot run start <run-id-or-name> [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 autopilot run pause

pause one autopilot run

Usage:
  warden autopilot run pause <run-id-or-name> [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 autopilot run resume

resume one autopilot run

Usage:
  warden autopilot run resume <run-id-or-name> [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 autopilot run stop

stop one autopilot run

Usage:
  warden autopilot run stop <run-id-or-name> [flags]

Flags:
  -h, --help   help for stop

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

warden autopilot run unregister

unregister one autopilot run

Usage:
  warden autopilot run unregister <run-id-or-name> [flags]

Flags:
  -h, --help   help for unregister

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

warden schedule

Create timer-driven triggers that the daemon fires on a schedule: a recurring
cron spec (--cron "0 9 * * *") or a single-shot time (--at 2026-06-27T09:00).
Each schedule fires either one agent spawn (the default — pass --type/--repo/
--prompt) or a pipeline (--pipeline <spec.yaml>). The scheduler is opt-in: set
scheduler_enabled: true in the config file and keep the daemon running.

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
  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

Create a recurring (--cron) or single-shot (--at) schedule. By default a
schedule fires one agent spawn — pass --type, --repo, --prompt (and optionally
--agent name / --branch). Pass --pipeline <spec.yaml> instead to fire a pipeline
(its name is timestamp-suffixed per fire so recurring runs don't collide).
Provide exactly one of --cron/--at and exactly one fire mode.

Usage:
  warden schedule create <name> (--cron <spec> | --at <time>) [--type <t> --repo <p> --prompt <s> | --pipeline <spec.yaml>] [flags]

Flags:
      --agent string      optional name for the spawned agent
      --at string         single-shot time, RFC3339 or 2006-01-02T15:04 (local)
      --branch string     optional development branch / pr-review checkout
      --cron string       recurring cron spec, e.g. "0 9 * * *" (minute hour dom month dow)
  -h, --help              help for create
      --pipeline string   fire a pipeline from this YAML spec file (instead of an agent)
      --prompt string     the agent's initial prompt
      --repo string       repo path (required for a typed agent)
      --type string       agent task type (e.g. pr-review, development); empty = free-form

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

warden schedule list

List schedules

Usage:
  warden schedule 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 schedule show

Show one schedule, including its last-run outcome

Usage:
  warden schedule show <id> [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 schedule enable

Enable a schedule so it fires again (re-arms next run)

Usage:
  warden schedule 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 schedule disable

Disable a schedule so it stops firing (history preserved)

Usage:
  warden schedule 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 schedule delete

Delete a schedule

Usage:
  warden schedule 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

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

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

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

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

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
      --supervised               alias for --permission-mode acceptEdits
      --type string              task type: development|analysis|spike|pr-review|code|docs|website|debug-ci|tests|other
      --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

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

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

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

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 -f <spec.yaml>` instead. The `preset`, `prompt-template`,
and `pipeline list-templates` 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

Show both libraries in two labeled sections: saved spawn presets (name +
their stored defaults) and the built-in pipeline templates (name + a short
description). Reuses the same sources as `warden preset list` and `warden
pipeline list-templates`.

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

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

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 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`)
  • 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)
  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

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

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 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

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

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

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

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

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

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

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)
  review               Run the agent backend's native diff review on the worktree
  guard                PreToolUse git-redirect guard (reads hook JSON on stdin)

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

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.

Usage:
  warden git commit [flags]

Flags:
  -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

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

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.

Usage:
  warden git sync [flags]

Flags:
      --base string   base branch to rebase onto (default main)
  -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 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 `pr-review` 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 `pr-review` agent.

Usage:
  warden git review [flags]

Flags:
      --backend 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 guard

PreToolUse git-redirect guard (reads hook JSON on stdin)

Usage:
  warden git guard [flags]

Flags:
  -h, --help   help for guard

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

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.

Usage:
  warden check [name] [flags]

Commands:
  run                  Run the project's configured checks and report only failures
  guard                PreToolUse check-redirect guard (reads hook JSON on stdin)
  boundary             PreToolUse isolation guard (reads hook JSON on stdin)
  root-guard           PreToolUse main-worktree guard (reads hook JSON on stdin)

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

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 guard

PreToolUse check-redirect guard (reads hook JSON on stdin)

Usage:
  warden check guard [flags]

Flags:
  -h, --help   help for guard

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

warden check boundary

PreToolUse isolation guard (reads hook JSON on stdin)

Usage:
  warden check boundary [flags]

Flags:
  -h, --help   help for boundary

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

warden check root-guard

PreToolUse main-worktree guard (reads hook JSON on stdin)

Usage:
  warden check root-guard [flags]

Flags:
  -h, --help   help for root-guard

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

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

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

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

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

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

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

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

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

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

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

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

Manage tool-permission prompts and the auto-approve policy.

List pending prompts with list, answer recognized menus by option number with
answer, and configure per-agent participation plus allow/deny rules under auto.

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

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

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

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

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

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

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

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

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

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

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

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 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
  repair               Offline, backup-first repair tools

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

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)

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

List the archived agent records the soft-delete path persists. Filter with --since (24h, 7d, 2w, or a date) and --type.

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)
      --since string   only agents updated since this window (24h, 7d, 2w) or date (2006-01-02 / RFC3339)
      --type string    filter by task type (development, pr-review, analysis, …)

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

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

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

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 repair

Offline, backup-first repair tools

Usage:
  warden inspect repair [flags]

Commands:
  sessions             Diagnose or reconstruct the offline session store

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 sessions

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 backend

Inspect and manage warden's agent-backend registry.

warden detects the coding-agent CLIs installed on this machine (claude, codex,
aider, …) plus a reserved `local` row for the free/local model, 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 and the internal
free/local thinking router both read from it.

Tiers:   free | subscription | pay_per_use | unclassified   (`local` is system-set)
Thinking-mode: local_only | free_plus_local   (which backends internal thinking may call)

Examples:
  warden backend backend list                 # full table incl. the local row
  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
  warden backend backend thinking-mode local_only

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
  thinking-mode        Set the internal-thinking routing mode (local_only|free_plus_local)
  tier                 Set a backend's billing tier (free|subscription|pay_per_use|unclassified)
  model                Inspect and manage model catalog and live model menus
  suggest              Recommend local models for the REPL, sized to this machine's memory
  repl                 Interactive REPL for agents, pipelines, and the git/check lifecycle (local LLM + `/` 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

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

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

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

List every backend in the registry, including the reserved local row, 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

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 thinking-mode

Set which backends warden's internal free/local thinking router may call.

  local_only        # route internal thinking to the local model only
  free_plus_local   # prefer free cloud backends, fall back to the local model (default)

Paid (subscription / pay_per_use) backends are never called for internal
thinking in either mode.

Usage:
  warden backend thinking-mode <mode> [flags]

Flags:
  -h, --help   help for thinking-mode

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

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

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)

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

Usage:
  warden backend model [flags]

Commands:
  list                 List models in the catalog and their assigned tiers
  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 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 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

Suggest local LLM models for warden's REPL (wd repl), ranked against
this machine's memory.

warden auto-detects two figures: total memory (GPU VRAM, Apple unified memory, or
system RAM — whichever bounds a usable model) and average free memory (sampled a
few times to smooth out spikes). Each candidate is then marked:

  fits now           runnable right now within free memory
  free memory first  fits the machine, but you'd need to close apps first
  too large          won't fit this machine

Models are scored by suitability for the conductor role — reliable tool/function
calling, not coding or raw size. The recommendation (★) is the best-scoring model
that runs comfortably now while leaving headroom for your real workload (Docker,
DBs, IDE, Claude sessions, the warden daemon). warden only ever recommends — you
set local_llm_model yourself.

Usage:
  warden backend suggest [flags]

Flags:
      --free-gb float    override detected free memory (GB)
  -h, --help             help for suggest
      --json             output as JSON
      --samples int      free-memory samples to average (default 5)
      --total-gb float   override detected total memory (GB)

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

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 the local LLM 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>). With a local
model present 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. Requires local_llm: true for the
natural-language half; the `/` commands work regardless.

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

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

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

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

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

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 by default; when local_llm is enabled the summary is narrated by the local model (and degrades to the deterministic text on any model error).

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 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.*— local-model, REPL, and LLM-offload settings

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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

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, ollama).

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 and Ollama use their 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 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

Run preflight checks (required binaries, daemon, data dir, configured local model)

Usage:
  warden doctor [flags]

Flags:
  -h, --help       help for doctor
      --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

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 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

Spawn an agent. --role is required (see 'warden role list'); there is no
implicit fallback role.

Free-form:   warden start --role <ROLE> "<prompt>" [--dir <path>]   (autonomous)
Interactive: warden start --role <ROLE> --dir <path>                (opens the agent and waits)
Managed:     warden start --role <ROLE> TICKET --type <TYPE>        (isolated worktree)

The spawn's backend+model is resolved (top wins): an explicit --backend/--model
pin > --tier (or --task, which derives a tier) routed through the quota-balanced
resolver > the resolver routed by --role alone > warden's configured defaults.
So --role on its own is always enough to spawn — --tier/--backend/--model are
optional refinements, not additional requirements.

Backends (--backend): warden drives Claude Code by default. Accepted values:
  claude (default, stable), aider, opencode, codex, crush, goose, cursor, antigravity.
Only claude is fully tested; codex and antigravity are beta, the rest experimental / WIP.
Terminal (--kind terminal): not an AI agent — opens a plain interactive shell ($SHELL)
in --dir, managed with the same worktree/git/tmux lifecycle as any agent. It is a
session kind, not a backend, so --backend/--model/--role/prompt are ignored.
Aider: BYO model (pass --model), no resume, runs a one-shot --message task.
OpenCode: BYO model (pass --model), structured transcript, DOES resume.
Codex: BYO provider (via ~/.codex/config.toml), DOES resume (dir-scoped).
Crush: BYO model (config-driven TUI; --model for headless), DOES resume (dir-scoped); initial prompt auto-typed post-launch.
Goose: BYO provider (GOOSE_PROVIDER/GOOSE_MODEL env), DOES resume (name-deterministic); no --model on session launch.
Cursor: hosted model catalog; pass --model to override (cursor-agent --list-models / wd models); DOES resume (dir-scoped --continue); warden owns the worktree (cursor's own -w never passed).
Antigravity: Google-hosted agy; defaults gemini-3.5-flash; pass --model (agy models / wd models); DOES resume (dir-scoped agy -c).
All non-claude backends show tokens-only spend. Claude remains full-fidelity.

Usage:
  warden start --role <ROLE> [TICKET|"<prompt>"] [--type <TYPE>] [--dir <PATH>] [--backend <ID>] [flags]

Flags:
      --auto-restart                             auto-resume this agent if it crashes (errored), capped at a few attempts
      --backend warden start --help              agent backend: claude (default, stable) | aider | opencode | codex | crush | goose | cursor | antigravity — only claude is fully tested; codex/antigravity are beta, the rest experimental. See warden start --help for per-backend notes
      --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 codex fork                     fork an existing agent's recorded session into this new managed agent (codex codex fork): branches the source's conversation in a fresh sibling worktree off its branch, carrying its uncommitted tracked changes; the source keeps running. Defaults --type to development; the fork inherits the source's repo+backend. See `warden fork` for the shorthand
  -h, --help                                     help for start
      --in-repo                                  write-agent opt-out: run in the shared repo instead of an isolated worktree (ignored for pr-review)
      --kind string                              session kind: empty/agent (default) spawns an AI agent; terminal opens a plain interactive shell ($SHELL) in --dir (not an AI agent — --backend/--model/--role/prompt ignored)
      --model string                             claude model: opus, sonnet, haiku, fable, or full model ID (default: the model_default config setting, i.e. sonnet)
      --name string                              optional human-friendly name (max 32 chars, alphanumeric + hyphens/underscores)
      --permission-mode string                   permission mode: acceptEdits|auto|bypassPermissions|default|dontAsk|plan (default: from config or 'auto')
      --pr string                                PR number/url (pr-review)
      --preset warden preset                     load saved spawn defaults from a named preset (see warden preset); explicit flags override
      --prompt-template warden prompt-template   fill a saved prompt template (see warden prompt-template) as the spawn prompt; a positional prompt still wins
      --repo string                              repo path (default: current directory)
      --role warden role list                    REQUIRED — built-in agent role: general | 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 role list
      --set stringArray                          supply a prompt-template variable as VAR=value (repeatable, e.g. --set FILE=foo.go --set X=y)
      --supervised                               alias for --permission-mode acceptEdits (kept for backwards compatibility)
      --tags warden ls --tag                     comma-separated labels for grouping/filtering (e.g. --tags backend,urgent); searchable and filterable via warden ls --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 backend+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 --backend/--model still wins over the resolver
      --type string                              task type: development|analysis|spike|pr-review|code|docs|website|debug-ci|tests|other
      --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 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

Show full status for one session

Usage:
  warden status <TICKET> [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

Type a message into an agent's claude session and press Enter

Usage:
  warden send <TICKET> <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

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.

Usage:
  warden commit [flags]

Flags:
  -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

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

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.

Usage:
  warden sync [flags]

Flags:
      --base string   base branch to rebase onto (default main)
  -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)

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 path	Canonical path
warden adopt	warden agent adopt
warden agent role tier ls	warden agent role tier list
warden approvals	warden approval list
warden approve	warden approval answer
warden attach	warden agent attach
warden audit	warden inspect audit
warden audit log	warden inspect audit
warden auto-approve	warden approval auto set
warden auto-approve allow	warden approval auto allow
warden auto-approve clear	warden approval auto clear
warden auto-approve deny	warden approval auto deny
warden auto-approve disable	warden approval auto disable
warden auto-approve enable	warden approval auto enable
warden auto-approve policy	warden approval auto rules
warden auto-approve rules	warden approval auto rules
warden auto-approve show	warden approval auto rules
warden autopilot list	warden autopilot run list
warden autopilot off	warden autopilot disable
warden autopilot on	warden autopilot enable
warden autopilot pause	warden autopilot run pause
warden autopilot resume	warden autopilot run resume
warden autopilot start	warden autopilot run start
warden autopilot stop	warden autopilot run stop
warden autopilot unregister	warden autopilot run unregister
warden backend ls	warden backend list
warden backend model ls	warden backend model list
warden backends	warden backend
warden backends default	warden backend default
warden backends disable	warden backend disable
warden backends enable	warden backend enable
warden backends list	warden backend list
warden backends ls	warden backend list
warden backends rescan	warden backend rescan
warden backends thinking-mode	warden backend thinking-mode
warden backends tier	warden backend tier
warden branches	warden workspace branches
warden collab	warden workspace
warden collab conflicts	warden workspace conflicts
warden collab who-is-editing	warden workspace who-is-editing
warden cost	retained; no canonical equivalent
warden cost savings	warden usage savings
warden cost spend	warden usage spend
warden ctx	warden context
warden ctx append	warden context append
warden ctx cas	warden context cas
warden ctx del	warden context delete
warden ctx get	warden context get
warden ctx list	warden context list
warden ctx set	warden context set
warden delete	warden agent delete
warden digest	warden agent digest
warden done	warden agent done
warden export	warden inspect export
warden force-compact	warden agent compact set
warden fork	warden agent fork
warden handoff	warden agent handoff
warden history	warden inspect history
warden hook check-guard	warden check guard
warden hook git-guard	warden git guard
warden hook guard	warden check boundary
warden hook root-guard	warden check root-guard
warden i	warden backend repl
warden import	warden inspect import
warden insights	warden usage insights
warden interactive	warden backend repl
warden land	warden autopilot land
warden lib	warden project library
warden library	warden project library
warden library list	warden project library list
warden library save-preset	warden project preset save
warden library save-prompt	warden project prompt-template save
warden llm	warden backend suggest
warden llm suggest	warden backend suggest
warden mcp	warden daemon mcp
warden memory	warden project memory
warden models	warden backend model
warden models list	warden backend model list
warden models ls	warden backend model list
warden models tier	warden backend model tier
warden msg	warden message
warden msg inbox	warden message inbox
warden msg send	warden message send
warden msg wait	warden message wait
warden pipeline list-templates	warden pipeline template list
warden plugin	warden project plugin
warden plugin list	warden project plugin list
warden preset	warden project preset
warden preset list	warden project preset list
warden preset save	warden project preset save
warden project library save-preset	warden project preset save
warden project library save-prompt	warden project prompt-template save
warden prompt-template	warden project prompt-template
warden prompt-template list	warden project prompt-template list
warden prompt-template save	warden project prompt-template save
warden prompt-templates	warden project prompt-template
warden prune	warden workspace prune
warden pt	warden project prompt-template
warden recover	warden agent recover
warden remove-worktree	warden agent remove-worktree
warden repair	warden inspect repair
warden repair sessions	warden inspect repair sessions
warden repl	warden backend repl
warden restore	warden agent restore
warden review	warden git review
warden role	warden agent role
warden role list	warden agent role list
warden role set-tier	warden agent role set-tier
warden role tier	warden agent role tier
warden role tier list	warden agent role tier list
warden role tier ls	warden agent role tier list
warden rotate	warden agent rotate
warden savings	warden usage savings
warden schedule get	warden schedule show
warden search	warden inspect search
warden set-permission-mode	warden agent permission-mode set
warden set-role	warden agent role set
warden snapshot	warden workspace snapshot
warden snapshot create	warden workspace snapshot create
warden snapshot list	warden workspace snapshot list
warden snapshot restore	warden workspace snapshot restore
warden spend	warden usage spend
warden stats	warden inspect resources
warden stop	warden agent stop
warden switch	warden agent switch
warden tail	warden agent tail
warden terminate	warden agent terminate
warden token	warden daemon token
warden token generate	warden daemon token generate
warden token rotate	warden daemon token rotate
warden token show	warden daemon token show
warden worktree	warden workspace
warden worktree list	warden workspace list
warden worktree ls	warden workspace list
warden worktree prune	warden workspace prune