CLI reference

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

Projects

maestro project create <name> --repo <repo_path> [--desc <description>] [--workflow <workflow_path>]
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>]
maestro project delete <id>

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

Use --desc for durable Codex guidance, not just a label. Maestro includes project.description in the default implementation, review, and done prompts for every issue in that project.

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

Project creation and updates are local-only. If you need to bring in work from Jira or another tracker, translate it into local Maestro projects and issues through MCP or scripts.

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]

maestro init [repo_path] is a root-level alias for maestro 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.

Skills

maestro install --skills

Use this command to install the bundled Maestro skill into the current user’s personal Codex skill directory:

~/.agents/skills/maestro

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