CLI reference

Jump straight to the commands you need to create projects, supervise the loop, and step in without hunting through prose.

Projects

maestro project create <name> --repo <repo_path> [--desc <description>] [--workflow <workflow_path>] [--provider <kanban|linear>] [--provider-project-ref <ref>] [--provider-endpoint <url>] [--provider-assignee <value>]
maestro project list
maestro project show <id>
maestro project start <id> --api-url <url>
maestro project stop <id> --api-url <url>
maestro project update <id> [--name <name>] [--desc <description>] [--repo <repo_path>] [--workflow <workflow_path>] [--provider <kanban|linear>] [--provider-project-ref <ref>] [--provider-endpoint <url>] [--provider-assignee <value>]
maestro project delete <id>

Use project commands to register a repo, inspect the local tracker, configure project-level providers, and remove stale projects from the store.

start and stop are live control commands. They require --api-url because they talk to a running Maestro daemon over HTTP.

kanban is the default provider. linear support exists, but it is intentionally limited and does not support epics.

Epics

maestro epic create <name> --project <project_id> [--desc <description>]
maestro epic list [--project <project_id>]
maestro epic show <id>
maestro epic update <id> [--name <name>] [--project <project_id>] [--desc <description>]
maestro epic delete <id>

Issues

maestro issue create <title> [--desc <description>] [--project <id>] [--priority <n>] [--labels <label1,label2>] [--type <standard|recurring>] [--cron "<spec>"] [--enabled=<true|false>]
maestro issue list [--state <state>] [--project <id>] [--type <standard|recurring>]
maestro issue show <identifier>
maestro issue images add <identifier> <path>
maestro issue images list <identifier>
maestro issue images remove <identifier> <image_id>
maestro issue move <identifier> <state>
maestro issue update <identifier> [--title <title>] [--desc <description>] [--type <standard|recurring>] [--cron "<spec>"] [--enabled=<true|false>] [--pr-url <url>]
maestro issue execution <identifier> --api-url <url>
maestro issue retry <identifier> --api-url <url>
maestro issue run-now <identifier> --api-url <url>
maestro issue unblock <identifier> <blocker_identifier...>
maestro issue blockers set <identifier> [blocker_identifier...]
maestro issue blockers clear <identifier>
maestro issue delete <identifier>
maestro issue block <identifier> <blocker_identifier...>

Issue commands are the local queue manipulation layer. Most day-to-day supervision boils down to create, list, move, show, execution inspection, blocker management, and attaching local screenshots to the issue record.

Recurring issues use --type recurring with a 5-field cron expression in the daemon host’s local timezone. run-now triggers an immediate recurring execution without waiting for the next scheduled slot.

issue images stores files locally beside the active database. The current implementation accepts PNG, JPEG, WEBP, and GIF files up to 10 MiB each.

Orchestration

maestro --log-level <debug|info|warn|error> run [repo_path] [--workflow <path>] [--extensions <json-file>] [--db <path>] [--logs-root <path>] [--log-max-bytes <n>] [--log-max-files <n>] [--port <port>]
maestro --log-level <debug|info|warn|error> mcp [--db <path>]
maestro --log-level <debug|info|warn|error> status [--json]
maestro --log-level <debug|info|warn|error> status --dashboard --api-url <url>
maestro --log-level <debug|info|warn|error> sessions --api-url <url>
maestro --log-level <debug|info|warn|error> events --api-url <url> [--since <seq>] [--limit <n>]
maestro --log-level <debug|info|warn|error> runtime-series --api-url <url> [--hours <n>]
maestro --log-level <debug|info|warn|error> verify [--repo <path>] [--db <path>] [--json]
maestro --log-level <debug|info|warn|error> doctor [--repo <path>] [--db <path>] [--json]
maestro --log-level <debug|info|warn|error> spec-check [--repo <path>] [--json]
maestro --log-level <debug|info|warn|error> workflow init [repo_path]

--log-level defaults to warn. Use info when you want lifecycle and status transition logs, and debug when you need raw app-server stream output and session churn in the structured logs.

maestro run serves HTTP on port 8787 by default. Pass --port only when you want a different port.

Live runtime helpers require --api-url because they talk to a running daemon over HTTP.

Issue states

State	Meaning
`backlog`	Not yet prioritized
`ready`	Available for the orchestrator
`in_progress`	Actively being worked
`in_review`	Waiting for human review
`done`	Completed
`cancelled`	Closed without completion

Common operator flows

Put a single issue into execution

maestro issue list --state backlog
maestro issue move ISS-1 ready
maestro run

Verify a repo before launching the loop

maestro verify --repo /path/to/repo --json
maestro doctor --repo /path/to/repo --json
maestro spec-check --repo /path/to/repo --json

Inspect live status without opening the dashboard

maestro status --dashboard --api-url http://127.0.0.1:8787
maestro sessions --api-url http://127.0.0.1:8787
maestro events --api-url http://127.0.0.1:8787

Getting Started

Core Concepts

Reference

Advanced