maestro-cli Command Reference

Generated from the CLI command tree by maestro-cli reference. Do not edit by hand - run npm run gen:cli-reference to refresh.

`maestro-cli agent-run`

Record and inspect agent runs

`maestro-cli agent-run record`

Record or update an agent run from a JSON file

Option	Description	Default
`--file <json>`	Agent run JSON file	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli agent-run append-event <run-id>`

Append an event to an agent run

Option	Description	Default
`--type <type>`	Event type	-
`--status <status>`	Update the run status with this event	-
`--message <text>`	Human-readable event message	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli agent-run list`

List recent agent runs

Option	Description	Default
`--status <status>`	Filter by run status	-
`--campaign <id>`	Filter by campaign id	-
`--limit <n>`	Maximum number of runs to show	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli agent-run show <run-id>`

Show an agent run and its events

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli campaign`

Record and inspect agent campaigns

`maestro-cli campaign record`

Record or update a campaign from a JSON file

Option	Description	Default
`--file <json>`	Campaign JSON file	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli campaign list`

List campaigns

Option	Description	Default
`--status <status>`	Filter by campaign status	-
`--limit <n>`	Maximum number of campaigns to show	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli campaign show <id>`

Show a campaign

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli list`

List resources

`maestro-cli list groups`

List all session groups

Option	Description	Default
`--json`	Output as JSON lines (for scripting)	-

`maestro-cli list agents`

List all agents

Option	Description	Default
`-g, --group <id>`	Filter by group ID	-
`--json`	Output as JSON lines (for scripting)	-

`maestro-cli list playbooks`

List playbooks (optionally filter by agent)

Option	Description	Default
`-a, --agent <id>`	Agent ID (shows all if not specified)	-
`--json`	Output as JSON lines (for scripting)	-

`maestro-cli list sessions <agent-id>`

List agent sessions (most recent first)

Option	Description	Default
`-l, --limit <count>`	Maximum number of sessions to show (default: 25)	-
`-k, --skip <count>`	Number of sessions to skip for pagination (default: 0)	-
`-s, --search <keyword>`	Filter sessions by keyword in name or first message	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli list ssh-remotes`

List all configured SSH remotes

Option	Description	Default
`--json`	Output as JSON lines (for scripting)	-

`maestro-cli list terminals`

List open terminal tabs in the desktop app (all agents unless —agent is given)

Option	Description	Default
`-a, --agent <id>`	Only list terminals belonging to this agent	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli show`

Show details of a resource

`maestro-cli show agent <id>`

Show agent details including history and usage stats

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli show playbook <id>`

Show detailed information about a playbook

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli playbook <playbook-id>`

Run a playbook

Option	Description	Default
`--dry-run`	Show what would be executed without running	-
`--no-history`	Do not write history entries	-
`--json`	Output as JSON lines (for scripting)	-
`--debug`	Show detailed debug output for troubleshooting	-
`--verbose`	Show full prompt sent to agent on each iteration	-
`--no-synopsis`	Skip synopsis generation after each task (reduces overhead)	-
`--wait`	Wait for agent to become available if busy	-
`--model <model>`	Model to use for this run only, overriding the agent’s configured default	-
`--effort <effort>`	Reasoning effort for this run only, overriding the agent’s configured default	-
`--ignore-model-hints`	Ignore MAESTRO:MODEL markers in the documents and run every task at —model/—effort (or the agent default)	-

`maestro-cli goal-run <agent-id> <goal>`

Launch a Goal-Driven Auto Run: pursue a free-text goal until done

Option	Description	Default
`--exit-criteria <text>`	What “done” looks like and when to declare a deadlock	-
`--max-iterations <n>`	Cap iterations (default: infinite)	-
`--no-history`	Do not write history entries	-
`--json`	Output as JSON lines (for scripting)	-
`--verbose`	Show full prompt sent to agent on each iteration	-
`--visible`	Run inside the Maestro desktop app (visible Auto Run) instead of headlessly	-
`--wait`	With —visible, wait for the agent to become available if busy	-
`--model <model>`	Model to use for this run only, overriding the agent’s configured default	-
`--effort <effort>`	Reasoning effort for this run only, overriding the agent’s configured default	-

`maestro-cli run-doc <docs>`

Run one or more Auto Run documents headlessly (no saved playbook required)

Option	Description	Default
`-a, --agent <id>`	Target agent by ID or name (use “maestro-cli list agents” to find agents)	-
`-p, --prompt <text>`	Custom prompt for the run (defaults to the Auto Run prompt)	-
`--loop`	Enable looping	-
`--max-loops <n>`	Maximum loop count (implies —loop)	-
`--reset-on-completion`	Enable reset-on-completion for all documents	-
`--dry-run`	Show what would be executed without running	-
`--no-history`	Do not write history entries	-
`--json`	Output as JSON lines (for scripting)	-
`--debug`	Show detailed debug output for troubleshooting	-
`--verbose`	Show full prompt sent to agent on each iteration	-
`--no-synopsis`	Skip synopsis generation after each task (reduces overhead)	-
`--wait`	Wait for agent to become available if busy	-
`--model <model>`	Model to use for this run only, overriding the agent’s configured default	-
`--effort <effort>`	Reasoning effort for this run only, overriding the agent’s configured default	-
`--ignore-model-hints`	Ignore MAESTRO:MODEL markers in the documents and run every task at —model/—effort (or the agent default)	-

`maestro-cli clean`

Clean up orphaned resources

`maestro-cli clean playbooks`

Remove playbooks for deleted sessions

Option	Description	Default
`--dry-run`	Show what would be removed without actually removing	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli send <agent-id> <message>`

Send a message to an agent and get a JSON response

Option	Description	Default
`-s, --session <id>`	Resume an existing agent session (for multi-turn conversations)	-
`-r, --read-only`	Run in read-only/plan mode (agent cannot modify files)	-
`-t, --tab`	Open/focus the session tab in Maestro desktop	-
`--require-plugin-tools`	Fail if a desktop-backed run with plugin tools is unavailable	-
`--require-tool-receipt <tool-id>`	Require a host-observed delivery receipt from this plugin tool ID	-
`--no-system-prompt`	Skip the Maestro system prompt (agent identity, git branch, history path, conductor profile). Default is to include it for parity with the desktop app.	-
`--no-history`	Do not write a History entry for this turn (written by default, desktop app running or not)	-
`--no-synopsis`	Skip the synopsis turn; the History entry carries the response instead	-

`maestro-cli dispatch <agent-id> <message>`

Dispatch a prompt to an agent in the Maestro desktop app and return its tab/session ID

Option	Description	Default
`--new-tab`	Create a fresh AI tab and deliver the prompt into it. A working agent cannot start a second turn, so the prompt is queued for the new tab and runs when the current turn ends (the response reports queued: true).	-
`--background`	Leave the view where it is (default with —new-tab; suppresses the agent switch otherwise)	-
`-t, --tab <id>`	Target an existing tab by its tab id (mutually exclusive with —new-tab)	-
`-f, --force`	Bypass the busy-state guard when writing to a busy tab; requires allowConcurrentSend (cannot be combined with —new-tab, which queues instead)	-
`--focus`	Switch to and focus the target agent/tab when dispatching (by default dispatch runs in the background without stealing focus)	-
`--queue`	If the target tab is busy, queue the prompt into the execution queue (FIFO) instead of rejecting it; an idle target dispatches immediately. Cannot be combined with —new-tab (which already queues when the agent is busy) or —force. Returns the queue position.	-
`--wait`	Alias for —queue	-
`--notify-on-complete <agent-id>`	Wake this agent with a real turn in its live tab when THIS dispatch finishes. Correlated to the dispatched tab, fires exactly once, and waits for a multi-task Auto Run to finish rather than firing per task. Requires —new-tab or —tab.	-
`--callback-tab <id>`	Specific tab of the —notify-on-complete agent to wake (default: its active AI tab)	-
`--callback-prompt <text>`	Override the callback prompt body. {{DISPATCH_STATUS}}, {{DISPATCH_TAB_ID}}, {{DISPATCH_TARGET_ID}}, {{DISPATCH_OUTPUT}}, {{DISPATCH_DURATION}}, {{DISPATCH_TASKS_COMPLETED}}, {{DISPATCH_TASKS_TOTAL}}, {{DISPATCH_PROMPT}} and {{DISPATCH_CALLBACK_ID}} are substituted.	-
`--callback-timeout <seconds>`	Give up and fire a timeout callback after this long (default 3600, max 86400)	-

`maestro-cli ask <agent-id> <question>`

Ask another agent a question and print its answer (background consult - never touches the target’s open conversation)

Option	Description	Default
`--from <agent-id>`	Your own agent id. Names the consult on the target, keeps continuity across repeat asks, forwards your working directory so it can read your project, and lets Stop cancel the consult. Defaults to the agent this runs under inside Maestro	-
`--with-context`	Forward your current transcript as context. Off by default: ask sends a self-contained question in a fresh context	-
`--timeout <seconds>`	How long to wait for the answer (default 600, min 10, max 3600)	-
`--json`	Output the answer as JSON	-

ask is a background consult: it prints an answer without touching the target agent’s open conversation. dispatch hands over work in a visible tab and returns a tab ID. Ask a self-contained question, or pass --with-context to include your transcript. The consult is recorded in the target’s history.

maestro-cli ask "Substrate PedTome" "How does your authentication gate work?" --from "$MY_AGENT_ID"

`maestro-cli queue`

Inspect and manage the desktop execution queue (from dispatch —queue)

`maestro-cli queue list`

List queued execution items as JSON (all agents, or one with —agent)

Option	Description	Default
`-a, --agent <id>`	Only list items for this agent (default: every agent with queued items)	-

`maestro-cli queue remove <item-id>`

Remove a queued item by its id (from dispatch —queue output or queue list)

Option	Description	Default
`-a, --agent <id>`	Agent whose queue the item belongs to (required)	-

`maestro-cli queue steer <item-id>`

Steer a queued message into the turn already running on its tab, like the Steer button on the queued card (Claude agents on the interactive token source, or Codex agents on the app-server transport). The item leaves the queue once the agent has it and returns if the agent never takes it.

Option	Description	Default
`-a, --agent <id>`	Agent whose queue the item belongs to (required)	-

`maestro-cli window`

List Maestro windows, and move agents or whole groups between them

`maestro-cli window list`

List open windows and the agents each one holds

Option	Description	Default
`--json`	Output as JSON	-

`maestro-cli window move-agent <agent-id>`

Move an agent (with its worktrees) to another window

Option	Description	Default
`--to <window>`	”new”, “main”, a window number, a window id, or a window name	-
`--json`	Output as JSON	-

`maestro-cli window move-group <group-id>`

Move every agent in a group (with subgroups when nesting is on) to another window

Option	Description	Default
`--to <window>`	”new”, “main”, a window number, a window id, or a window name	-
`--json`	Output as JSON	-

`maestro-cli snooze`

Park a tab until later, and manage what is parked

`maestro-cli snooze tab <tab-id> <when>`

Snooze a tab or tiled group until <when> (e.g. 2h, tomorrow, “next fri 3pm”)

Option	Description	Default
`-a, --agent <id>`	Agent that owns the tab. Required for a file, terminal, browser, or group tab, which are not in the AI tab list	-
`-n, --note <text>`	Note-to-self surfaced in the wake notification	-
`-p, --wake-prompt <text>`	Prompt sent to the agent the moment the tab comes back (AI tabs and groups only)	-
`--background`	Park it without flashing the “Snoozed until …” confirmation	-
`--focus`	Show the confirmation flash (the default)	-
`--json`	Output the stored snooze as JSON	-

`maestro-cli snooze list`

List snoozed tabs across every agent, soonest wake first

Option	Description	Default
`-a, --agent <id>`	Only list snoozes held by this agent	-
`--json`	Output as JSON	-

`maestro-cli snooze wake <snooze-id>`

Bring a snoozed tab back right now (accepts a unique id prefix)

Option	Description	Default
`--background`	Accepted and ignored: a wake restores the tab without focusing it	-
`--focus`	Accepted and ignored: a wake restores the tab without focusing it	-
`--json`	Output as JSON	-

`maestro-cli snooze dismiss <snooze-id>`

Drop a snooze and its tab - it won’t come back

Option	Description	Default
`--background`	Dismiss it without raising the “Snooze dismissed” toast	-
`--focus`	Raise the toast (the default)	-
`--json`	Output as JSON	-

`maestro-cli snooze reschedule <snooze-id> <when>`

Move a snooze to a new time, optionally rewriting its note or wake prompt

Option	Description	Default
`-n, --note <text>`	Replace the note (pass an empty string to clear it)	-
`-p, --wake-prompt <text>`	Replace the wake prompt (empty string clears it)	-
`--json`	Output as JSON	-

`maestro-cli snooze history`

Snoozes that have already resolved - woken, unsnoozed, or dismissed

Option	Description	Default
`--limit <n>`	Only show the newest <n> entries	-
`--json`	Output as JSON	-

`maestro-cli unsnooze <snooze-id>`

Bring a snoozed tab back right now (alias for “snooze wake”)

Option	Description	Default
`--background`	Accepted and ignored: a wake restores the tab without focusing it	-
`--focus`	Accepted and ignored: a wake restores the tab without focusing it	-
`--json`	Output as JSON	-

`maestro-cli session`

Inspect open desktop tabs and their conversation history

`maestro-cli session list`

List open desktop AI tabs and their tab/session IDs

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli session show <tab-id>`

Print conversation history for a desktop tab

Option	Description	Default
`--since <timestamp>`	Only return messages after this timestamp (ISO-8601 or epoch ms/sec)	-
`--tail <n>`	Only return the last N messages (applied after —since)	-
`--json`	Output as JSON (for scripting); default is a formatted transcript	-

`maestro-cli group-chat`

Start, message, and inspect group chats in the desktop app

`maestro-cli group-chat start <name>`

Create a group chat and send its moderator the opening message

Option	Description	Default
`-p, --participant <agent>`	Participant agent ID or name (repeatable; at least one)	`[]`
`--moderator <agent-type>`	Moderator agent type (e.g. claude-code); defaults to the first participant’s type	-
`-m, --message <text>`	Opening message for the moderator (defaults to the name)	-
`--message-file <path>`	Read the opening message from a file	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli group-chat send <chat> [message]`

Send a message to a group chat (ID, ID prefix, or name); refused while busy

Option	Description	Default
`--message-file <path>`	Read the message from a file	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli group-chat status <chat>`

Show a group chat’s state, participants, and latest messages

Option	Description	Default
`--tail <n>`	How many recent messages to print (default 5; 0 for none)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli group-chat list`

List group chats and whether each is busy

Option	Description	Default
`--all`	Include archived chats	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli group-chat stop <chat>`

Stop a group chat’s moderator and participants

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli open-file <file-path>`

Open a file as a preview tab in the Maestro desktop app (audio and video play in the floating media player instead; an http(s) URL to an MP4 or audio file streams in the player)

Option	Description	Default
`-a, --agent <id>`	Target agent (defaults to auto-detect by file path’s owning agent)	-
`--background`	Open the preview tab without changing anything currently rendered, on any agent	-
`--focus`	Switch to the file after opening it (default)	-
`--no-switch`	Don’t switch to the target agent, but still activate the tab there	-
`--queue`	Audio/video only: add to the media player queue and show the player without starting playback	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli open-graph [paths]`

Open the Document Graph over specific markdown files or a directory

Option	Description	Default
`-a, --agent <id>`	Target agent (defaults to auto-detect by path’s owning agent)	-
`--focus <path>`	Center the graph on this document (default: the most-linked one)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli open-browser <url>`

Open a URL as a browser tab in the Maestro desktop app

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (defaults to active)	-
`--background`	Create the tab without focusing it or switching agents (use for agent research, then close-browser when done)	-
`--focus`	Switch to the browser tab after opening it (default)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli open [surface]`

Open a Maestro modal or dashboard (use —list to see every surface)

Option	Description	Default
`-t, --tab <tab>`	Deep-link to a tab within the surface	-
`--list`	List every openable surface, its tabs, and its shortcut	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli image`

List and save images pasted into a Maestro chat

`maestro-cli image list`

List images pasted into an agent’s conversation, newest first

Option	Description	Default
`-a, --agent <id>`	Only this agent (defaults to every agent)	-
`-t, --tab <tab-id>`	Only this AI tab	-
`--limit <n>`	Maximum images to show (default: 20)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli image save [target]`

Save a pasted image to disk (target: index, handle, or “latest”)

Option	Description	Default
`-a, --agent <id>`	Only this agent (defaults to every agent)	-
`-t, --tab <tab-id>`	Only this AI tab	-
`-o, --output <path>`	File or directory to write (default: a generated name in the cwd)	-
`--all`	Save every image in scope instead of just the newest	-
`--force`	Overwrite an existing file named by —output	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli close-browser <tab-id>`

Close a browser tab in the Maestro desktop app (owning agent resolved by tab ID)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli open-terminal`

Open a new terminal tab in the Maestro desktop app

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (defaults to active)	-
`--cwd <path>`	Working directory for the terminal (must be within the agent’s cwd)	-
`--shell <shell>`	Shell binary to use (default: zsh)	-
`--name <name>`	Display name for the tab	-
`--command <command>`	Command to run in the terminal (kept as the startup command, so it re-runs if the tab restarts)	-
`--background`	Create the tab without moving the view (agent and tab stay put)	-
`--input-required`	Notify the user that this terminal needs human input	-
`--focus`	Switch to the terminal tab after opening it (default)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli send-terminal [command]`

Run a command in an existing Maestro terminal tab

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (defaults to active)	-
`--tab <id-or-name>`	Terminal tab ID or display name (defaults to the agent’s active terminal)	-
`--control <letter>`	Send a control character instead of a command (e.g. C for Ctrl-C)	-
`--no-enter`	Type the command without pressing Enter	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli read-terminal`

Read a Maestro terminal tab’s output

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (defaults to active)	-
`--tab <id-or-name>`	Terminal tab ID or display name (defaults to the agent’s active terminal)	-
`--tail <n>`	Return only the last N lines (default: 200)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli refresh-files`

Refresh the file tree in the Maestro desktop app (never moves the view)

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (defaults to active)	-
`--background`	Accepted and ignored: this refresh never moves the view or shows a notice	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli refresh-auto-run`

Refresh Auto Run documents in the Maestro desktop app

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (defaults to active)	-
`--background`	Refresh without switching to the target agent (default)	-
`--focus`	Switch to the target agent while refreshing	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli auto-run <docs>`

Configure and optionally launch an auto-run with documents

Option	Description	Default
`-a, --agent <id>`	Target agent by ID (use “maestro-cli list agents” to find IDs)	-
`-p, --prompt <text>`	Custom prompt for the auto-run	-
`--loop`	Enable looping	-
`--max-loops <n>`	Maximum loop count (implies —loop)	-
`--save-as <name>`	Save as a playbook with this name (don’t launch)	-
`--launch`	Start the auto-run immediately (default: just configure)	-
`--reset-on-completion`	Enable reset-on-completion for all documents	-
`--worktree`	Run the auto-run inside a git worktree (requires —launch, —branch, —worktree-path)	-
`--branch <name>`	Branch name for the worktree (created if it does not exist)	-
`--base-branch <name>`	Ref the new branch should be based on when it does not yet exist (e.g. “rc” or “main”). Defaults to the main repo HEAD.	-
`--worktree-path <path>`	Filesystem path for the worktree (must be a sibling of the repo)	-
`--create-pr`	Open a GitHub PR when the auto-run completes successfully	-
`--pr-target-branch <branch>`	Target branch for the PR (defaults to the repo default branch)	-
`--model <model>`	Model to use for this run only, overriding the agent’s configured default	-
`--effort <effort>`	Reasoning effort for this run only, overriding the agent’s configured default	-
`--ignore-model-hints`	Ignore MAESTRO:MODEL markers in the documents and run every task at —model/—effort (or the agent default)	-

`maestro-cli stop-auto-run`

Stop the active Auto Run for an agent

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli resume-auto-run`

Resume an Auto Run that paused on an error

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli skip-auto-run`

Skip the current document of an error-paused Auto Run and continue

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli abort-auto-run`

Abort an error-paused Auto Run

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli reset-auto-run-tasks <filename>`

Reset all completed [x] tasks back to [ ] in an Auto Run document

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli auto-run-status`

Show whether an Auto Run is active and its document/task progress

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli auto-run-folder <path>`

Point an agent at a different Auto Run folder (relative paths resolve against this shell’s cwd)

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli marketplace`

Browse and import Playbook Exchange playbooks (the modal: open marketplace)

`maestro-cli marketplace list`

List playbooks in the official + local catalog

Option	Description	Default
`-c, --category <name>`	Only this category	-
`-s, --search <text>`	Match id, title, description, or tags	-
`--refresh`	Bypass the catalog cache	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli marketplace show <playbook-id>`

Show a playbook’s details, documents, and README

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli marketplace import <playbook-id>`

Install a playbook into an agent’s Auto Run folder

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`-f, --folder <name>`	Folder name under the Auto Run folder (default: from the title)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli remove-playbook <agent-id> <playbook-id>`

Remove a saved playbook from an agent (find IDs via “list playbooks -a <agent>“)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue`

Interact with Maestro Cue automation

`maestro-cli cue trigger <subscription-name>`

Manually trigger a Cue subscription by name

Option	Description	Default
`-p, --prompt <text>`	Override the subscription prompt with custom text	-
`--json`	Output as JSON (for scripting)	-
`--source-agent-id <id>`	Agent ID to pass as source context for write-back	-

`maestro-cli cue list`

List all Cue subscriptions across agents

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue enable <subscription>`

Turn a Cue subscription on (name, or the full id from cue list --json)

Option	Description	Default
`-a, --agent <id>`	Disambiguate a name several agents share	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue disable <subscription>`

Turn a Cue subscription off without deleting it

Option	Description	Default
`-a, --agent <id>`	Disambiguate a name several agents share	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue activity`

Show recent Cue runs, newest first

Option	Description	Default
`-a, --agent <id>`	Only runs for this agent	-
`-n, --limit <n>`	How many runs to show (default 20)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue schedule`

Create a scheduled task (or —list / —cancel / —reschedule / —pause)

Option	Description	Default
`--in <duration>`	One-shot: fire after a relative delay (e.g. 30s, 20m, 2h, 1d)	-
`--at <timestamp>`	One-shot: fire at ISO-8601 timestamp or “YYYY-MM-DD HH:MM” (local)	-
`--daily-at <times>`	Repeating: comma-separated HH:MM times (e.g. 09:00,17:30)	-
`--days <days>`	Limit —daily-at to these days (e.g. mon,tue,wed,thu,fri)	-
`--every <duration>`	Repeating: fire on an interval (e.g. 30m, 2h, 1d)	-
`--list`	List scheduled tasks across agents	-
`--kind <kind>`	Filter —list by kind: once, daily, interval, all (default: all)	-
`--cancel <name>`	Cancel a scheduled task by name	-
`--reschedule <name>`	Change when an existing task fires (pass the timing flag too)	-
`--pause <name>`	Disable a task without deleting it	-
`--resume <name>`	Re-enable a paused task	-
`-a, --agent <id-or-name>`	Target agent (required when creating; scopes other modes)	-
`-p, --prompt <text>`	Prompt to send when the task fires. With —auto-run: extra instructions for the run	-
`--auto-run <documents...>`	Launch an Auto Run of these .md documents (inside the agent’s Auto Run folder) instead of sending a prompt. Kept on a failed launch	-
`--reset-on-completion`	With —auto-run: uncheck every task when the run finishes	-
`--loop`	With —auto-run: re-run the documents once every task is checked off	-
`--max-loops <n>`	With —auto-run: loop ceiling (implies —loop)	-
`--per-document`	With —auto-run: one agent turn per document instead of one per task	-
`--ignore-model-hints`	With —auto-run: ignore the documents’ MAESTRO:MODEL hints	-
`--no-auto-resume`	With —auto-run: stay paused after an agent error	-
`--auto-resume-after <minutes>`	With —auto-run: minutes between auto-resume attempts	-
`--max-auto-resumes <n>`	With —auto-run: auto-resume attempt ceiling	-
`--worktree-branch <name>`	With —auto-run: create a worktree on this branch when the run fires, and run there	-
`--worktree-agent <id-or-name>`	With —auto-run: run in this already-open worktree agent	-
`--worktree-path <path>`	With —auto-run: run in the worktree already on disk at this path	-
`--base-branch <ref>`	With a worktree flag: ref a new branch is cut from, and the pull request target	-
`--create-pr`	With a worktree flag: open a pull request when the run finishes	-
`--notify`	Show a toast notification when the task fires	-
`--sticky`	Make the notify toast sticky (requires —notify)	-
`-m, --message <text>`	Body for the notify toast (defaults to label/prompt)	-
`-n, --name <name>`	Custom subscription name (auto-generated when omitted)	-
`-l, --label <text>`	Human-readable label (defaults to truncated prompt)	-
`--pipeline <name>`	Pipeline name (default: Tasks)	-
`--grace-minutes <n>`	Override the default 360-minute grace window	-
`--tier <level>`	Model tier for the prompt run: low, medium, high (mapped per provider)	-
`--model <id>`	Exact model id for the prompt run (instead of —tier). With —auto-run: model for this run only	-
`--effort <level>`	Effort for the prompt run: low, medium, high (mapped per provider). With —auto-run: reasoning effort for this run only	-
`--keep-on-failure`	Keep the subscription on a failed/timed-out run (default: self-destructs on both success and failure)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue pipeline`

Manage Cue pipeline layout entries (cue-pipeline-layout.json)

`maestro-cli cue pipeline list`

List all pipelines in the layout file

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue pipeline get <name>`

Print one pipeline entry as JSON to stdout

Option	Description	Default
`--json`	Output as JSON (default; flag kept for parity)	-

`maestro-cli cue pipeline export <name>`

Alias for get: print one pipeline entry as JSON to stdout

Option	Description	Default
`--json`	Output as JSON (default; flag kept for parity)	-

`maestro-cli cue pipeline add <name>`

Add a new pipeline entry from a JSON file

Option	Description	Default
`--from <file>`	JSON file with one pipeline entry (matches `get` output)	-
`--force`	Replace any existing pipeline with the same name/id	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue pipeline replace <name>`

Replace an existing pipeline entry from a JSON file

Option	Description	Default
`--from <file>`	JSON file with one pipeline entry (matches `get` output)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue pipeline remove <name>`

Remove a pipeline entry by name or id

Option	Description	Default
`--force`	Suppress the no-op error when the pipeline is already absent	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue engine`

Run Maestro Cue unattended (no desktop app) and control that runner

`maestro-cli cue engine start`

Start the Cue engine in this process and block until Ctrl+C / stopped

Option	Description	Default
`--json`	Print machine-readable start/failure status	-

`maestro-cli cue engine stop`

Stop a running standalone engine (refuses to signal a desktop-owned one)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-
`--wait-ms <ms>`	How long to wait for the lock to clear after signaling	-

`maestro-cli cue engine status`

Report whether an engine is running and its last known heartbeat

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli cue engine inspect`

List every agent with a readable .maestro/cue.yaml and its subscription counts

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli director-notes`

Director’s Notes: unified history and AI synopsis

`maestro-cli director-notes history`

Show unified history across all agents

Option	Description	Default
`-d, --days <n>`	Lookback period in days (default: from app settings)	-
`-f, --format <type>`	Output format: json, markdown, text (default: text)	-
`--filter <type>`	Filter by entry type: auto, user, cue, agent	-
`-l, --limit <n>`	Maximum entries to show (default: 100)	-
`--json`	Output as JSON (shorthand for —format json)	-

`maestro-cli director-notes synopsis`

Generate AI synopsis of recent activity (requires running Maestro app)

Option	Description	Default
`-d, --days <n>`	Lookback period in days (default: from app settings)	-
`-f, --format <type>`	Output format: json, markdown, text (default: text)	-
`--json`	Output as JSON (shorthand for —format json)	-

`maestro-cli status`

Check if the Maestro desktop app is running and reachable

`maestro-cli version`

Show the running Maestro app’s version and build commit hash

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli doctor`

Diagnose CLI connectivity, version skew, and configuration

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli completions <shell>`

Print a shell completion script (bash, zsh, or fish)

`maestro-cli reference`

Print the full command reference (Markdown, or —format json)

Option	Description	Default
`--format <format>`	Output format: md (default) or json	-

`maestro-cli create-agent <name>`

Create a new agent in the Maestro desktop app

Option	Description	Default
`-d, --cwd <path>`	Working directory for the agent	-
`-t, --type <type>`	Agent type (claude-code, codex, opencode, factory-droid, copilot-cli, antigravity, gemini-cli, qwen3-coder)	`"claude-code"`
`-g, --group <id>`	Group ID to assign the agent to	-
`--nudge <message>`	Nudge message appended to every user message	-
`--new-session-message <message>`	Message prefixed to first message in new sessions	-
`--custom-path <path>`	Custom binary path for the agent	-
`--custom-args <args>`	Custom CLI arguments for the agent	-
`--env <KEY=VALUE>`	Environment variable (repeatable)	`[]`
`--model <model>`	Model override (e.g., sonnet, opus)	-
`--effort <level>`	Effort/reasoning level override	-
`--context-window <size>`	Context window size in tokens	-
`--provider-path <path>`	Custom provider path	-
`--ssh-remote <id>`	SSH remote ID for remote execution	-
`--ssh-cwd <path>`	Working directory override on SSH remote	-
`--sync-history-to-remote <bool>`	Sync history entries to .maestro/history/ on the remote host (true/false; requires —ssh-remote)	-
`--auto-run-folder <path>`	Path to the agent Auto Run / playbooks folder (overrides the default <cwd>/.maestro/playbooks)	-
`--background`	Create the agent without selecting it (Left Bar selection stays put)	-
`--focus`	Select the new agent after creating it (default)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli create-group <name>`

Create a new group in the Maestro desktop app

Option	Description	Default
`-e, --emoji <emoji>`	Emoji icon for the group	-
`--icon <icon-id>`	Built-in icon ID (folder, briefcase, rocket, …) or a plugin icon ID. Mutually exclusive with —emoji	-
`--color <color>`	Label color as #RRGGBB, or a plugin color ID	-
`--parent <group-id>`	Create inside this root group	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli remove-group <group-id>`

Remove a group from the Maestro desktop app (agents inside are ungrouped, not deleted)

Option	Description	Default
`-f, --force`	Delete even if the group still has agents (ungroups them)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli rename-group <group-id> <new-name>`

Rename a group in the Maestro desktop app

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli update-group <group-id>`

Update a group’s name, icon, color, parent, or Left Bar visibility in the Maestro desktop app

Option	Description	Default
`-n, --name <name>`	New group name	-
`-e, --emoji <emoji>`	Emoji icon for the group. Mutually exclusive with —icon	-
`--icon <icon-id>`	Built-in icon ID (folder, briefcase, rocket, …) or a plugin icon ID. Mutually exclusive with —emoji	-
`--color <color>`	Label color as #RRGGBB, or a plugin color ID	-
`--parent <group-id>`	Move the group inside this root group	-
`--clear-emoji`	Reset the emoji to the default folder	-
`--clear-icon`	Remove the icon	-
`--clear-color`	Remove the label color	-
`--clear-parent`	Promote the group to the top level	-
`--hide`	Park the group out of the Left Bar. Its agents stay reachable through search and the switcher	-
`--show`	Bring a hidden group back into the Left Bar	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli create-worktree`

Create a new agent in a git worktree branched off an existing parent agent

Option	Description	Default
`-a, --agent <id>`	Parent agent ID the worktree branches from (use “maestro-cli list agents” to find IDs)	-
`-b, --branch <name>`	Branch name for the worktree (created if it does not exist)	-
`--base-branch <name>`	Ref the new branch is based on when it does not yet exist (e.g. “rc” or “main”). Defaults to the parent repo HEAD.	-
`-m, --message <text>`	Optional initial prompt to dispatch to the new agent after creation	-
`--background`	Create the agent without selecting it (Left Bar selection stays put)	-
`--focus`	Select the new worktree agent after creating it (default)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli remove-agent <agent-id>`

Remove an agent from the Maestro desktop app

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli update-agent <agent-id>`

Update an existing agent’s group, working directory, and per-agent settings

Option	Description	Default
`-g, --group <id>`	Move the agent to this group (use “none” to ungroup; supports partial IDs)	-
`-d, --cwd <path>`	Change the agent’s working directory (resolved to absolute; agent must be stopped)	-
`--ssh-remote <id>`	Set the SSH remote for remote execution (use “none” to revert to local; agent must be stopped)	-
`--ssh-cwd <path>`	Working directory override on the SSH remote	-
`--sync-history-to-remote <bool>`	Sync history entries to .maestro/history/ on the remote host (true/false)	-
`--nudge <message>`	Nudge message appended to every message (empty string clears)	-
`--new-session-message <message>`	Message prefixed to the first message of new sessions (empty string clears)	-
`--custom-path <path>`	Override the agent binary path (empty string clears)	-
`--custom-args <args>`	Custom CLI arguments for the agent (empty string clears)	-
`--env <KEY=VALUE>`	Set an environment variable (repeatable; replaces the env map)	`[]`
`--clear-env`	Clear all per-agent environment variables	-
`--model <model>`	Model override (e.g. sonnet, opus; empty string clears)	-
`--effort <level>`	Effort/reasoning level override (empty string clears)	-
`--context-window <size>`	Context window size in tokens (0 or “none” clears)	-
`--token-source <mode>`	Claude token source: api \| tui \| dynamic (Claude Code agents only)	-
`--maestro-p-path <path>`	Override the maestro-p binary path (empty string clears)	-
`--codex-transport <transport>`	Codex transport: exec \| app-server (experimental, enables steering; Codex only)	-
`--bookmark <bool>`	Bookmark the agent in the Left Bar (true/false)	-
`--provider <type>`	Switch the agent provider (resets tabs + clears provider config; requires —force)	-
`--force`	Confirm a destructive change (required for —provider)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli rename-agent <agent-id> <new-name>`

Rename an agent in the Maestro desktop app

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli bookmark <agent-id>`

Bookmark an agent (pins it to the Left Bar’s Bookmarks section)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli unbookmark <agent-id>`

Remove an agent’s bookmark

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli focus-agent <agent-id>`

Focus (select) an agent in the Maestro desktop UI

Option	Description	Default
`--tab <tab-id>`	Also focus this tab within the agent	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli switch-mode <agent-id> <mode>`

Switch an agent between “ai” and “terminal” mode

Option	Description	Default
`--background`	Refuse the switch if the agent is the one on screen, rather than changing what the user is looking at	-
`--focus`	Switch even when the agent is the one on screen (default)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab`

Manage an agent’s tabs in the desktop app

`maestro-cli tab new`

Open a new tab for an agent (optionally seeded with a prompt)

Option	Description	Default
`-a, --agent <id>`	Target agent ID	-
`-p, --prompt <text>`	Seed the new AI tab with this prompt	-
`--background`	Create the tab without moving the view (agent and tab stay put)	-
`--focus`	Switch to the new tab after creating it (default)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab close <tab-id>`

Close a tab (owning agent is resolved automatically)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab rename <tab-id> <new-name>`

Rename a tab

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab star <tab-id>`

Star a tab

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab unstar <tab-id>`

Unstar a tab

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab unread <tab-id>`

Mark a tab unread (flags it for the human in the tab bar)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab read <tab-id>`

Clear a tab’s unread marker

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab save-to-history <tab-id> <bool>`

Enable/disable synopsizing this tab’s completions into History (true/false)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab show <tab-id>`

Show one tab’s settings (model, effort, thinking, access, history)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab thinking <tab-id> <mode>`

Set the thinking display: off, on, sticky, or cycle

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab read-only <tab-id> <bool>`

Put the tab in read-only/plan mode so the agent cannot modify files

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab model <tab-id> <model>`

Override the model for this tab (“inherit” clears the override)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab effort <tab-id> <level>`

Override the effort/reasoning level for this tab (“inherit” clears it)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab enter-to-send <tab-id> <bool>`

Per-tab send key: true = Enter, false = Cmd+Enter, “inherit” = global setting

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli tab move <tab-id> <position>`

Move a tab to a position in its agent’s tab bar (0-based, or “first”/“last”)

Option	Description	Default
`-a, --agent <id>`	Whose active tab, when <tab-id> is “active”	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli create-ssh-remote <name>`

Create a new SSH remote configuration

Option	Description	Default
`-H, --host <host>`	SSH hostname or IP (or SSH config Host pattern with —ssh-config)	-
`-p, --port <port>`	SSH port (default: 22)	-
`-u, --username <user>`	SSH username	-
`-k, --key <path>`	Path to private key file	-
`--env <KEY=VALUE>`	Remote environment variable (repeatable)	`[]`
`--ssh-option <KEY=VALUE>`	Extra ssh -o option, e.g. ProxyCommand=… or ConnectTimeout=45 (repeatable)	`[]`
`--ssh-config`	Use ~/.ssh/config for connection settings (host becomes Host pattern)	-
`--disabled`	Create in disabled state	-
`--set-default`	Set as the global default SSH remote	-
`--json`	Output as JSON (for scripting)	-

--ssh-option passes an option to ssh -o, overriding Maestro defaults and ~/.ssh/config. Use it for a tunnel ProxyCommand, a ProxyJump bastion, or a longer ConnectTimeout. RequestTTY is reserved because Maestro derives it per command; forcing a TTY can corrupt an agent’s stream-json output.

maestro-cli create-ssh-remote "Tunnelled box" \
  --host tailcat-devbox \
  --ssh-option "ProxyCommand=/opt/homebrew/bin/tailcat tcXXXX 22" \
  --ssh-option ConnectTimeout=45

`maestro-cli update-ssh-remote <remote-id>`

Update an existing SSH remote configuration

Option	Description	Default
`-n, --name <name>`	Display name	-
`-H, --host <host>`	SSH hostname, IP, or SSH config Host pattern	-
`-p, --port <port>`	SSH port	-
`-u, --username <user>`	SSH username (empty string clears it)	-
`-k, --key <path>`	Path to private key file (empty string clears it)	-
`--env <KEY=VALUE>`	Remote environment variable, merged with existing (repeatable)	`[]`
`--clear-env`	Remove all remote environment variables before applying —env	-
`--disable-env <KEY>`	Switch an env var off, keeping its value (repeatable)	`[]`
`--enable-env <KEY>`	Switch a previously disabled env var back on (repeatable)	`[]`
`--ssh-option <KEY=VALUE>`	Extra ssh -o option, merged with existing (repeatable)	`[]`
`--clear-ssh-options`	Remove all extra ssh -o options before applying —ssh-option	-
`--disable-ssh-option <KEY>`	Switch an ssh -o option off, keeping its value (repeatable)	`[]`
`--enable-ssh-option <KEY>`	Switch a previously disabled ssh -o option back on (repeatable)	`[]`
`--ssh-config <bool>`	Use ~/.ssh/config for connection settings (true/false)	-
`--enabled <bool>`	Enable or disable this remote (true/false)	-
`--set-default`	Set as the global default SSH remote	-
`--json`	Output as JSON (for scripting)	-

Only supplied fields change. --env and --ssh-option merge with existing values; use --clear-env or --clear-ssh-options to start from empty. --disable-* keeps a value but stops passing it to SSH; --enable-* restores it. Clearing also removes disabled entries. JSON output includes sshOptions, disabled entries, and resolvedSshOptions (the effective options including defaults).

`maestro-cli remove-ssh-remote <remote-id>`

Remove an SSH remote configuration

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli test-ssh-remote <remote-id>`

Test an SSH remote connection and report what the remote answered

Option	Description	Default
`-a, --agent <command>`	Also check whether this binary is on the remote PATH	-
`--timeout <seconds>`	Give up after this many seconds	`60`
`--json`	Output as JSON (for scripting)	-

test-ssh-remote uses the same connection options as agent spawning and prints the remote hostname, so tunnel and ProxyCommand errors can be caught during setup. It also works while the desktop is closed.

`maestro-cli display`

View and manage typography (fonts, sizes, zoom)

`maestro-cli display font [surface] [value]`

Get or set a surface font. Surfaces: interface, terminal, chat, filePreview, documentGraph, fileEditor. Pass “inherit” (or “inherit:terminal”) to follow a root surface. Omit the surface to list all.

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli display size <surface> [value]`

Get or set a surface font size in px. Pass “inherit” to follow the interface size.

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli display zoom [level]`

Get or set the global zoom applied to every surface (e.g. 125% or 1.25)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli display preset [name]`

Get the active typography preset, or reset every font and size to one (default | hacker)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli display fonts`

List the fonts bundled with Maestro (guaranteed available on any machine)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli settings`

View and manage Maestro configuration

`maestro-cli settings list`

List all settings with current values

Option	Description	Default
`--json`	Output as JSON lines (for scripting)	-
`-v, --verbose`	Show descriptions for each setting (useful for LLM context)	-
`--keys-only`	Show only setting key names	-
`--defaults`	Show default values alongside current values	-
`-c, --category <name>`	Filter by category (e.g., appearance, shell, editor)	-
`--show-secrets`	Show sensitive values like API keys (masked by default)	-

`maestro-cli settings get <key>`

Get the value of a setting (supports dot-notation, e.g., encoreFeatures.directorNotes)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-
`-v, --verbose`	Show full details including description, type, and default	-

`maestro-cli settings set <key> <value>`

Set a setting value (auto-detects type: bool, number, JSON, string)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-
`--raw <json>`	Pass an explicit JSON value (bypasses auto type coercion)	-

`maestro-cli settings reset <key>`

Reset a setting to its default value

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli settings media-status`

Report media tools available to this CLI process and allowed models as JSON

`maestro-cli settings agent`

View and manage per-agent configuration

`maestro-cli settings agent list [agent-id]`

List agent configurations (all agents or a specific one)

Option	Description	Default
`--json`	Output as JSON lines (for scripting)	-
`-v, --verbose`	Show descriptions for each config key	-

`maestro-cli settings agent get <agent-id> <key>`

Get a single agent config value

Option	Description	Default
`--json`	Output as JSON (for scripting)	-
`-v, --verbose`	Show full details including description	-

`maestro-cli settings agent set <agent-id> <key> <value>`

Set an agent config value (auto-detects type)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-
`--raw <json>`	Pass an explicit JSON value (bypasses auto type coercion)	-

`maestro-cli settings agent reset <agent-id> <key>`

Remove an agent config key

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli set-theme [name-or-id]`

Switch the active Maestro theme (applies live). Use —list to see options.

Option	Description	Default
`-l, --list`	List available themes	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli gloss [level]`

Set the surface gloss level: off, sheen, strong or max (applies live). Omit the level to see the current one.

Option	Description	Default
`-l, --list`	List the gloss levels and what each one does	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli theme`

Manage the custom theme palette

`maestro-cli theme show`

Print the current custom theme palette and base (reads from disk)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli theme export`

Export the custom theme as portable JSON (stdout, or —file <path>)

Option	Description	Default
`-f, --file <path>`	Write the theme JSON to this file instead of stdout	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli theme import <file>`

Import a theme JSON file, apply it live, and activate it

Option	Description	Default
`--no-activate`	Save the palette without switching to the Custom theme	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli theme set [assignments]`

Set custom theme colors (key=value, e.g. accent=#ff0000) and/or re-base

Option	Description	Default
`-b, --base <id>`	Initialize from a built-in theme before applying overrides	-
`-a, --activate`	Switch to the Custom theme after applying	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli encore`

List and toggle experimental Encore features

`maestro-cli encore list`

List Encore features and whether each is enabled

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli encore enable <feature>`

Enable an Encore feature (directorNotes, usageStats, symphony, maestroCue, pianola, computerHistory, quickChat, maestroRun)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli encore disable <feature>`

Disable an Encore feature

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history`

Computer History: query what the user saw and typed across apps (local, untrusted content)

`maestro-cli computer-history status`

Show whether recording is on, permission state, and store size

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history list`

List recorded 15-minute segments in a time range

Option	Description	Default
`--since <time>`	Start: 30m, 2h, 1d, 1w, ISO-8601, or epoch (default 2h)	-
`--until <time>`	End (default now)	-
`--app <id>`	Only segments that include this app id	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history query`

Search recorded events (text, selections, snapshots, app and window changes)

Option	Description	Default
`--since <time>`	Start: 30m, 2h, 1d, 1w, ISO-8601, or epoch (default 1h)	-
`--until <time>`	End (default now)	-
`--app <id>`	App id or name (comma list or repeat)	`[]`
`--kind <kind>`	text \| selection \| snapshot \| app \| window (comma list or repeat)	`[]`
`--grep <regex>`	Case-insensitive regex over text, titles, URLs, and labels	-
`--limit <n>`	Most recent N matches (default 200)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history apps`

Apps used in a time range, by foreground time and event count

Option	Description	Default
`--since <time>`	Start (default 1d)	-
`--until <time>`	End (default now)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history digests`

List 15-minute digests and 6-hour roll-ups (agent-written, untrusted content)

Option	Description	Default
`--since <time>`	Start: 30m, 2h, 1d, 1w, ISO-8601, or epoch (default 1d)	-
`--until <time>`	End (default now)	-
`--kind <kind>`	15m \| 6h (default both)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history pause`

Pause recording (until resumed, or for a duration)

Option	Description	Default
`--for <duration>`	Pause for 30m, 2h, 1d, 1w (default: until resumed)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history resume`

Resume recording

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history rules`

Which apps are recorded (exclude or include mode) and domains never recorded

`maestro-cli computer-history rules list`

Show the app mode and user rules (built-in exclusions always apply)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history rules mode [mode]`

Show or set the app mode: exclude (record every app except ignored ones) or include (record only the record-only list)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history rules add`

Never record an app or a domain (and its subdomains); with —include, add an app to the record-only list

Option	Description	Default
`--app <id>`	App id or exact name: macOS bundle id, Windows exe name, Linux desktop id	-
`--domain <domain>`	Domain, e.g. bank.example.com	-
`--include`	Add the app to the record-only list used in include mode	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history rules remove <id>`

Remove a rule by id (or by its app id / domain)

Option	Description	Default
`--include`	When removing by value, remove it from the record-only list	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history clear`

Delete recorded history: everything since a time, or all of it

Option	Description	Default
`--since <time>`	Delete what was recorded since: 30m, 2h, 1d, 1w, ISO-8601	-
`--all`	Delete all recorded history (settings and rules stay)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history enable-accessibility`

macOS: show the Accessibility prompt. Linux: turn on the desktop accessibility bus. Windows: not needed

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli computer-history config`

Show settings, or change them with the flags below

Option	Description	Default
`--retention-days <n>`	Keep this many days (default 90)	-
`--max-gb <n>`	Keep at most this many GB (default 25)	-
`--snapshots <on\|off>`	Record visible window text snapshots	-
`--digests <on\|off>`	Have an agent write 15-minute digests (off by default)	-
`--digest-agent <id>`	Agent that writes digests (empty string clears it)	-
`--digest-rollup <on\|off>`	Also write 6-hour roll-ups from the 15-minute digests (default on)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola`

Pianola manager agent: watch tabs, auto-answer or escalate per your rules

`maestro-cli pianola watch <tab-id>`

Watch a desktop tab and act on awaiting-input prompts per your rules

Option	Description	Default
`--agent <agent-id>`	Agent id to dispatch answers to (defaults to the tab owner)	-
`--interval <seconds>`	Polling interval in seconds (default 5)	-
`--dry-run`	Classify and record decisions but never send a message	-
`--once`	Run a single iteration instead of looping	-
`--json`	Reserved for scripting; affects the disabled-feature error only	-

`maestro-cli pianola rules`

List the configured Pianola rules

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola add-rule`

Add a Pianola rule (how the manager agent turns a conversation into a durable rule)

Option	Description	Default
`--scope <scope>`	global \| project \| tab (default global)	-
`--scope-id <id>`	Project path (scope project) or tab id (scope tab)	-
`--action <action>`	auto_answer \| escalate \| ignore (required)	-
`--answer <text>`	Reply text (required for auto_answer)	-
`--max-risk <risk>`	Only fire when risk is at most: low \| medium \| high	-
`--kinds <list>`	Comma list of signal kinds: question,blocked,none	-
`--topic-includes <list>`	Comma list of case-insensitive topic substrings	-
`--priority <n>`	Lower runs first (default 100)	-
`--description <text>`	Human-readable description	-
`--disabled`	Create the rule disabled	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola learn`

Crawl installed CLI transcripts into a labeled decision corpus (Claude Code + Codex)

Option	Description	Default
`--agent <list>`	Comma list of agents to crawl: claude-code,codex (default both)	-
`--limit <n>`	Max sessions per agent, newest first (default 300)	-
`--since <date>`	Only crawl transcripts modified on/after this date (e.g. 2026-06-01)	-
`--project <substr>`	Only keep decisions from sessions whose path contains this substring	-
`--exclude <substr>`	Drop decisions from sessions whose path contains this substring	-
`--max-pairs <n>`	Max decision pairs to print inline when —out is not used (default 200)	-
`--out <file>`	Write the full corpus JSON to a file instead of stdout	-
`--json`	Compact JSON output (for scripting)	-

`maestro-cli pianola profile`

Read a learned decision profile (per-project with —project, else global)

Option	Description	Default
`--project <path>`	Project path to read the profile for (falls back to global)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola set-profile`

Save a learned decision profile from —file or stdin (per-project or global)

Option	Description	Default
`--project <path>`	Project path this profile is for (omit for the global profile)	-
`--file <path>`	Read the profile markdown from this file (else reads stdin)	-
`--pair-count <n>`	How many decision pairs this profile was synthesized from	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola log`

Show recent Pianola decisions from the audit log

Option	Description	Default
`--limit <n>`	Maximum number of records to show (default 20)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola plan`

Author and inspect Pianola task plans (DAGs)

`maestro-cli pianola plan set`

Save a plan from —file or piped stdin (validated before write)

Option	Description	Default
`--file <path>`	Read the plan JSON from this file (else reads stdin)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola plan list`

List saved plans with a progress summary

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola plan show <planId>`

Show one plan: its tasks, statuses, and dependencies

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola orchestrate <planId>`

Run a saved plan to completion, dispatching tasks as their dependencies finish

Option	Description	Default
`--interval <seconds>`	Polling interval in seconds (default 5)	-
`--concurrency <n>`	Max tasks running at once (default 3)	-
`--once`	Run a single iteration instead of looping	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola supervise`

`maestro-cli pianola supervise watch <tabId>`

Option	Description	Default
`--agent <agent-id>`	Agent id to dispatch answers to (required)	-
`--interval <seconds>`	Polling interval in seconds (default 5)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola supervise orchestrate <planId>`

Option	Description	Default
`--concurrency <n>`	Max tasks running at once (default 3)	-
`--interval <seconds>`	Polling interval in seconds (default 5)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola supervise list`

List registered supervised targets

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola supervise remove <id>`

Unregister a supervised target by id (the desktop stops its child)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola supervise enable <id>`

Enable a supervised target by id

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli pianola supervise disable <id>`

Disable a supervised target by id (the desktop stops its child)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli prompts`

Read Maestro system prompts

`maestro-cli prompts list`

List all known prompt ids with descriptions

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli prompts get <id>`

Print a prompt by id (honors user customizations from Settings → Maestro Prompts)

Option	Description	Default
`--json`	Output as JSON object with metadata + content	-

`maestro-cli gist`

Publish session context to GitHub gists

`maestro-cli gist create <agent-id>`

Publish an agent’s session transcript as a GitHub gist (requires running Maestro app)

Option	Description	Default
`-d, --description <text>`	Gist description	-
`-p, --public`	Create a public gist (default: private)	-
`-s, --session <id>`	Publish one provider session’s transcript (from `send -s <id>`) instead of the agent’s open desktop tabs	-

`maestro-cli notify`

Show notifications in the Maestro desktop app

`maestro-cli notify toast <title> <message>`

Show a toast notification (queued, click X or icon to dismiss)

Option	Description	Default
`-c, --color <color>`	green \| yellow \| orange \| red \| theme (default: theme)	-
`-t, --timeout <seconds>`	Auto-dismiss after N seconds (range: (0, 60]; omitted = app default)	-
`--dismissible`	Sticky toast - no auto-dismiss; user must click to close. Cannot combine with —timeout	-
`-a, --agent <id>`	Associate with an agent so clicking jumps to it	-
`--source-agent <label>`	Label shown in the toast header identifying which agent/pipeline fired it. Store-independent, so it shows even for cron/watchdog toasts. Wins over the name resolved from —agent; pair with —agent to also get click-to-jump	-
`--tab <id>`	AI tab ID within the agent - clicking jumps to that tab (requires —agent)	-
`--action-url <url>`	Inline link rendered beneath the message body (opens in browser when clicked)	-
`--action-label <text>`	Label for —action-url (defaults to the URL itself)	-
`--open-file <path>`	On click, switch to the agent and open this file in its File Preview pane (requires —agent; mutually exclusive with the other —open-* flags)	-
`--open-terminal [tab]`	On click, switch to the agent and focus a terminal tab. Optional value is a tab id or name; bare uses the active terminal tab (requires —agent)	-
`--open-browser <url>`	On click, open this URL in a new in-app browser tab on the agent (requires —agent)	-
`--open-browser-tab <id>`	On click, focus this existing in-app browser tab (the id `open-browser` printed; requires —agent)	-
`--open-url <url>`	On click, open this URL in the system browser (opens outside Maestro; use —open-browser for an in-app tab)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli notify flash <message>`

Show a center-screen flash (momentary, exclusive - replaces any active flash)

Option	Description	Default
`-c, --color <color>`	green \| yellow \| orange \| red \| theme (default: theme)	-
`-D, --detail <text>`	Optional second line shown beneath the message	-
`-t, --timeout <seconds>`	Auto-dismiss after N seconds (range: (0, 5]; default 1.5)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli profiling`

Start/stop a Chromium performance capture in the desktop app (for perf iteration)

`maestro-cli profiling start`

Begin a performance capture (no-ops if one is already recording)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli profiling stop`

Stop the capture and write the compressed .zip bundle to —output

Option	Description	Default
`-o, --output <path>`	Destination .zip path (absolute or relative to cwd; ~ expanded). Parent dirs are created.	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli profiling status`

Report whether a capture is currently recording

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli maestro-run`

MaestroRun (macOS): install the launcher and grant it Full Disk Access for scheduled scripts

`maestro-cli maestro-run status`

Re-check the launcher: installed version, signature, and Full Disk Access

Option	Description	Default
`--check-latest`	Also ask GitHub for the newest release	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli maestro-run install`

Download, verify, and install the newest MaestroRun release for this Mac (or update it)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli maestro-run grant`

Open System Settings on the Full Disk Access list and watch for the switch (the user flips it)

Option	Description	Default
`--reveal`	Also show MaestroRun.app in Finder, for dragging into the list	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat`

Drive the Quick Chat window: a floating chat with one agent, summoned by a hotkey

`maestro-cli quick-chat show`

Open the Quick Chat window (same as the hotkey when it is closed)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat hide`

Close the Quick Chat window; the conversation is kept

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat toggle`

Open the window, focus it, or close it (exactly what the hotkey does)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat status`

Show the window state, the agent, the mode, and the current conversation

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat send <message>`

Send a message in the current Quick Chat (starts a chat if none is open)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat new`

Start a new chat (an ephemeral previous chat is deleted)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat keep [state]`

Keep the current chat as a visible tab on its agent (“off” makes it ephemeral)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat pin [state]`

Float the window above other windows (“off” lets it fall behind them)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat font [size]`

Text size of the conversation: in, out, reset, or a size such as 120% (no size prints it)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat agent <agent-id>`

Switch Quick Chat to another agent and start a new chat there

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat reveal [message-id]`

Open a tab of the chat in the main Maestro window: the tab a message went to, or the latest

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat new-tab [message-id]`

Send a message that is queued behind a busy tab to a new tab instead (default: the latest queued one)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat stop`

Stop the replies in progress and withdraw the messages still queued

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli quick-chat bounds`

Move or resize the window, as dragging it does, and remember it (—height is the conversation height)

Option	Description	Default
`--x <px>`	Left edge, in screen points (give with —y)	-
`--y <px>`	Top edge, in screen points (give with —x)	-
`--width <px>`	Width	-
`--height <px>`	Height of the conversation shape	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cadenza`

Open small cadenza views to display or track work in the Maestro desktop app

`maestro-cli cadenza open <id>`

Open (or replace by id) a cadenza view

Option	Description	Default
`--type <type>`	tracker \| file \| markdown \| image \| code \| view \| html \| decision (default: tracker)	-
`--title <text>`	Header label for the panel	-
`--body <text>`	Body content - tracker line, markdown/code source, JSON block spec (—type view), HTML document, or decision prompt	-
`--body-file <path>`	Read body content from a file (markdown, view JSON, code, or HTML)	-
`--path <path>`	File/image path (required for file and image; for —type code, shows that file as a snippet)	-
`--lang <lang>`	Language for —type code highlighting (inferred from —path if omitted)	-
`--option <label:value>`	A decision button (repeatable); clicking replies value to —agent. Requires —type decision	`[]`
`-c, --color <color>`	green \| yellow \| orange \| red \| theme (default: theme)	-
`-a, --agent <id>`	Owning agent - lets a file cadenza expand into its tab, and the reply target for —type decision	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cadenza update <id>`

Update fields of an open cadenza in place (the living view)

Option	Description	Default
`--title <text>`	New header label	-
`--body <text>`	New body content (tracker line or markdown source)	-
`--body-file <path>`	Read new body content from a file	-
`--path <path>`	New file/image path	-
`-c, --color <color>`	green \| yellow \| orange \| red \| theme	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli cadenza close <id>`

Close a cadenza view by id

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement`

Compose the agent-driven movement (free-placed data views) in the Maestro main window

`maestro-cli movement begin <id>`

Immediately show a host-rendered Concerto shell before its HTML is ready

Option	Description	Default
`--title <text>`	Concerto title shown in its frame	-
`--x <px>`	X position (px from the Concerto stage left)	-
`--y <px>`	Y position (px from the Concerto stage top)	-
`--width <px>`	Shell width in px (default: 880)	-
`--height <px>`	Shell height in px (default: 560)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement add <id>`

Add (or replace by id) a native data view or interactive HTML mockup

Option	Description	Default
`--type <type>`	view \| html (default: view)	-
`--x <px>`	X position (px from movement left)	-
`--y <px>`	Y position (px from movement top)	-
`--width <px>`	Item width in px (default: 500 view, 880 html)	-
`--height <px>`	Optional fixed item height in px (default: fit content)	-
`--title <text>`	Item header title	-
`--body <content>`	Block spec JSON for —type view, or a complete document for —type html	-
`--body-file <path>`	Read the view JSON or HTML document from a file	-
`--html-file <path>`	Read an HTML document from a file (implies —type html)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement update <id>`

Update fields of an existing movement item in place

Option	Description	Default
`--type <type>`	Switch or confirm the item type: view \| html	-
`--x <px>`	New X position	-
`--y <px>`	New Y position	-
`--width <px>`	New width	-
`--height <px>`	New fixed height	-
`--title <text>`	New title	-
`--body <content>`	New block spec JSON or HTML document	-
`--body-file <path>`	Read the new view JSON or HTML document from a file	-
`--html-file <path>`	Read a new HTML document from a file (implies —type html)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement move <id>`

Reposition a movement item

Option	Description	Default
`--x <px>`	New X position	-
`--y <px>`	New Y position	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement remove <id>`

Remove a movement item by id

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement clear`

Remove all movement items

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement progress <id>`

Report one Concerto track’s current design phase and subdivision

Option	Description	Default
`--title <text>`	Concerto title shown in the pipeline	-
`--phase <phase>`	composing \| refining \| arranging \| reviewing \| testing	-
`--step <n>`	Active one-based substep (default: 1)	-
`--steps <n>`	Planned substeps in this phase, 1 through 8 (default: 1)	-
`--notes <pattern>`	Comma-separated quarter/eighth/sixteenth notes with optional +dotted, +triad, or +tie	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement state`

Read the current movement layout (items + size) to compose around it

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement inspect <id>`

Capture a live HTML Movement preview and report its runtime diagnostics

Option	Description	Default
`--output <png>`	Write the live mockup screenshot to this PNG path	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli movement interact <id>`

Interact with a live HTML Movement by CSS selector

Option	Description	Default
`--click <selector>`	Click the matching element	-
`--type <selector>`	Enter text into the matching input or editable element	-
`--value <text>`	Text used with —type	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli support-package`

Write a sanitized support (debug) package zip, as Create Debug Package does, without a save dialog

Option	Description	Default
`-o, --output <dir>`	Directory to write maestro-debug-<timestamp>.zip into (created if missing; ~ expanded)	-
`--no-logs`	Leave out application logs	-
`--no-errors`	Leave out recent errors	-
`--no-sessions`	Leave out agent/session metadata	-
`--no-group-chats`	Leave out group chat metadata	-
`--no-batch-state`	Leave out Auto Run state	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli feedback`

Send Feedback from the CLI: check gh, find duplicates, +1 an issue, or file a new one (open the modal with open feedback)

`maestro-cli feedback auth`

Check that the GitHub CLI (gh) is installed, logged in, and allowed to file on the feedback repo (required to file); names the gh account, and prints the login command when signing in can fix it

Option	Description	Default
`--fresh`	Skip the cached verdict (after logging in elsewhere)	-
`--json`	Output as JSON (for scripting)	-

Sign the GitHub CLI in for feedback (gh auth login, device code + browser), as the modal’s “Log in to GitHub” does

Option	Description	Default
`--json`	Output the result as JSON (for scripting)	-

`maestro-cli feedback accounts`

List the provider accounts the Feedback chat can run as, in the order it tries them (first usable one wins)

Option	Description	Default
`--use <key>`	Make this account (a key from the list) the one the next chat tries first	-
`--clear`	Forget the remembered account and pick automatically again	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli feedback diagnose`

Read the live app state the Feedback chat starts from: agents that are busy, errored, limit-paused, retrying, or running Auto Run, plus recent warnings and errors (redacted, read-only)

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli feedback search <query>`

Search RunMaestro/Maestro for issues matching a description

Option	Description	Default
`--json`	Output as JSON (for scripting)	-

`maestro-cli feedback submit`

File a GitHub issue exactly as the Feedback modal does. Stops on likely duplicates unless —force

Option	Description	Default
`-c, --category <category>`	bug \| feature \| improvement \| general	-
`-s, --summary <text>`	One-line summary (max 120 chars; becomes the title)	-
`-e, --expected <text>`	Expected behavior (bug) or desired outcome (other categories)	-
`-a, --actual <text>`	Actual behavior (bug) or details (other categories)	-
`--steps <text>`	Steps to reproduce	-
`--context <text>`	Additional context	-
`--attach <image...>`	Screenshots to attach: PNG, JPG, GIF, or WebP, up to 5 files, 10 MB each	-
`--support-package`	Generate a sanitized support package and link it from the issue (the modal checkbox)	-
`--force`	File even when possible duplicates exist	-
`--json`	Output as JSON (for scripting)	-

Add a +1 to an existing issue instead of filing a duplicate

Option	Description	Default
`--comment <text>`	Also post this comment on the issue	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli stats`

Show aggregated Usage Dashboard metrics for a time range

Option	Description	Default
`-r, --range <range>`	Time range: day, week, month, quarter, year, all (default: week)	-
`--json`	Output the full aggregation object as JSON	-

`maestro-cli stats-query <sql>`

Run a read-only SQL query against the stats database (SELECT / read PRAGMA only)

Option	Description	Default
`-p, --param <value>`	Bind a value to a positional ? placeholder (repeatable, in order)	`[]`
`--json`	Output rows as JSON instead of a tab-separated table	-

`maestro-cli plugin`

Author, validate, sign, and package Maestro plugins

`maestro-cli plugin list`

Read installed plugin versions, load status, and enable state from the desktop

Option	Description	Default
`--json`	Output as JSON	-

`maestro-cli plugin update <dir>`

Update an installed plugin from a local package directory, preserving data

Option	Description	Default
`--json`	Output the resulting plugin registry as JSON	-

`maestro-cli plugin init [dir]`

Scaffold a new plugin in <dir> (defaults to the current directory)

Option	Description	Default
`--tier <0\|1\|2>`	Plugin trust/capability tier (default 1)	-
`--id <id>`	Plugin id (defaults to a slug of the directory name)	-
`--name <name>`	Human-readable plugin name (defaults to the id)	-
`--force`	Scaffold into a non-empty directory	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli plugin validate [dir]`

Validate <dir>/plugin.json and, when present, its signature.json

Option	Description	Default
`--trusted-key <keys>`	Comma-separated base64 public keys to treat as trusted when resolving signature status	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli plugin sign <dir>`

Sign <dir> with ed25519 and write signature.json

Option	Description	Default
`--key <path>`	Private key to sign with (PEM, or base64-encoded PKCS8 DER)	-
`--gen-key`	Generate a fresh ed25519 keypair (requires —key-out)	-
`--key-out <path>`	Where to write the generated private key (with —gen-key)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli plugin pack <dir>`

Package <dir> into a distributable archive (excludes node_modules/.git/keys)

Option	Description	Default
`--out <file>`	Output archive path (default <id>-<version>.tgz)	-
`--json`	Output as JSON (for scripting)	-

`maestro-cli mcp`

Model Context Protocol bridge for Maestro plugin tools

`maestro-cli mcp serve`

Run an MCP stdio server exposing registered plugin tools (spawned by an agent via its MCP config)

Option	Description	Default
`--tab <id>`	Originating desktop tab id (diagnostics only)	-

​maestro-cli Command Reference

​maestro-cli agent-run

​maestro-cli agent-run record

​maestro-cli agent-run append-event <run-id>

​maestro-cli agent-run list

​maestro-cli agent-run show <run-id>

​maestro-cli campaign

​maestro-cli campaign record

​maestro-cli campaign list

​maestro-cli campaign show <id>

​maestro-cli list

​maestro-cli list groups

​maestro-cli list agents

​maestro-cli list playbooks

​maestro-cli list sessions <agent-id>

​maestro-cli list ssh-remotes

​maestro-cli list terminals

​maestro-cli show

​maestro-cli show agent <id>

​maestro-cli show playbook <id>

​maestro-cli playbook <playbook-id>

​maestro-cli goal-run <agent-id> <goal>

​maestro-cli run-doc <docs>

​maestro-cli clean

​maestro-cli clean playbooks

​maestro-cli send <agent-id> <message>

​maestro-cli dispatch <agent-id> <message>

​maestro-cli ask <agent-id> <question>

​maestro-cli queue

​maestro-cli queue list

​maestro-cli queue remove <item-id>

​maestro-cli queue steer <item-id>

​maestro-cli window

​maestro-cli window list

​maestro-cli window move-agent <agent-id>

​maestro-cli window move-group <group-id>

​maestro-cli snooze

​maestro-cli snooze tab <tab-id> <when>

​maestro-cli snooze list

​maestro-cli snooze wake <snooze-id>

​maestro-cli snooze dismiss <snooze-id>

​maestro-cli snooze reschedule <snooze-id> <when>

​maestro-cli snooze history

​maestro-cli unsnooze <snooze-id>

​maestro-cli session

​maestro-cli session list

​maestro-cli session show <tab-id>

​maestro-cli group-chat

​maestro-cli group-chat start <name>

​maestro-cli group-chat send <chat> [message]

​maestro-cli group-chat status <chat>

​maestro-cli group-chat list

​maestro-cli group-chat stop <chat>

​maestro-cli open-file <file-path>

​maestro-cli open-graph [paths]

​maestro-cli open-browser <url>

​maestro-cli open [surface]

​maestro-cli image

​maestro-cli image list

​maestro-cli image save [target]

​maestro-cli close-browser <tab-id>

​maestro-cli open-terminal

​maestro-cli send-terminal [command]

​maestro-cli read-terminal

​maestro-cli refresh-files

​maestro-cli refresh-auto-run

​maestro-cli auto-run <docs>

​maestro-cli stop-auto-run

​maestro-cli resume-auto-run

​maestro-cli skip-auto-run

​maestro-cli abort-auto-run

​maestro-cli reset-auto-run-tasks <filename>

​maestro-cli auto-run-status

​maestro-cli auto-run-folder <path>

​maestro-cli marketplace

​maestro-cli marketplace list

​maestro-cli marketplace show <playbook-id>

​maestro-cli marketplace import <playbook-id>

​maestro-cli remove-playbook <agent-id> <playbook-id>

​maestro-cli cue