The muster CLI

Commands

muster [--socket <path>] <command> [args]

list   [--project <id>] [--json]     List open tasks
status [--project <id>] [--json]     Dashboard of tasks by state
wait   --task <id> --state <state> [--timeout <secs>]
                                     No maximum; omitted means 300s
spawn  <project_id> <name> [--agent <id>] [--profile <id>]
       [--worktree off|new] [--base <branch>] [--branch <name>]
       [--no-start] [--json]          Create a task AND start its agent
                                     (--no-start: create only)
attach <task_id> [--json]            How to attach to a task's terminal
close  <task_id> [--keep-worktree]   Close a task (kills its agent)
reopen <task_id>                     Reopen a closed task
resume <task_id>                     Relaunch the agent with its resume invocation
events [--json]                      Stream live state changes until disconnect
reload-config                        Re-read config.toml in the running app

policy list [--json]                 Policies + who depends on them
policy show <policy_id> [--json]     Resolved layers, revision, dead rows
policy presets [--json]              Built-in presets
policy set-project-default <project_id> (<policy_id> | --clear)
policy apply-preset <policy_id> <preset_id> --project <id>
       [--layer global|project|task] [--worktree <id>]
       [--db <id>]… [--host <id>]… [--force]
                                     --layer task on a SHARED policy is REFUSED
                                     without --force: it re-scopes every task on it

queue list [--json]                  Pending/running queue entries (headless, DB-direct)
queue enqueue <project_id> <name> [--prompt <text>] [--agent <id>]
         [--profile <id>] [--worktree] [--policy <id>] [--json]
                                     Enqueue an agent run (via the control socket)
queue cancel <entry_id> [--keep-worktree]
                                     Cancel an entry; a running one's agent is killed
queue remove <entry_id>              Drop an entry row
queue retry <entry_id>               Re-enqueue a failed/canceled run (fresh task)
queue clear --yes                    Drop every finished entry (destroys retry specs)
queue run [--once] [--interval-ms <n>]  Work the queue headlessly (no app needed)

--db and --host repeat: every occurrence is collected, so a preset that scopes its grants to picked resources authors a rule for each one you named.

Everything talks to the app's control socket, which --socket (or $MUSTER_CONTROL_SOCK) overrides — except queue list and queue run, which read the shared database directly and work with the app closed. queue run also starts queued entries for SSH-remote projects: it bootstraps and tunnels to the host exactly as the app does, from the same signed agent cache.

spawn starts the agent it creates, so the scripted spawn → wait → attach below works against an app whose window is on another virtual desktop — before 1.5 the agent only started when somebody selected the task, and the wait could only time out. --no-start keeps the old create-only behavior, and against an app too old to start agents the CLI says so on stderr rather than letting a script wait on an agent that is not running.

reload-config re-reads config.toml in the running app and prints exactly what it applied. Settings the orchestrator owns — post-create hooks, the default shell, the automations master switch — take effect immediately; the secret backend, daemon, terminal and notification settings still need a restart, and the reply says so rather than implying a full reload. A config.toml that is present but unparseable is refused outright, so a typo cannot silently reset the running app to defaults.

Exit codes & scripting

# Spawn work, block until it wants review, then show how to attach.
id=$(muster spawn "$PROJECT" "refactor the parser" --worktree new --json | jq -r .task.id)
if muster wait --task "$id" --state needs_review --timeout 1800; then
  muster attach "$id" --json
else
  echo "still running after 30m"   # exit code 2
fi