Skip to main content
The Maestro CLI provides powerful command-line tools for automating AI agents, running playbooks in batch mode, and managing agents programmatically. Perfect for CI/CD pipelines, scripting, and headless automation.

​
Installation

The Maestro CLI is included with the Maestro desktop application. Access it via: 
maestro-cli --version
The CLI reads agent configurations from the Maestro desktop app’s storage. Ensure you’ve created and configured agents in the desktop app before using CLI commands.

​
Key Features

Batch Playbook Execution

Run playbooks headlessly with full automation support

Agent Messaging

Send messages to agents and get JSON responses

JSONL Output

Machine-readable output for scripting and parsing

Session Management

List agents, groups, playbooks, and sessions

​
Quick Start

​
List All Agents

maestro-cli list agents
Output: 
AGENTS (3)

  Backend Engineer claude-code [Auto Run]
      /Users/dev/projects/api-server
      a1b2c3d4-...

  Frontend Dev codex
      /Users/dev/projects/web-app
      e5f6g7h8-...

​
Run a Playbook

maestro-cli playbook abc123 --json
Streams execution events in JSONL format: 
{"type":"start","timestamp":1709472000000}
{"type":"task_start","document":"Phase-01.md","taskIndex":0}
{"type":"task_complete","success":true,"summary":"Created API endpoint"}
{"type":"complete","totalTasksCompleted":12}

​
Send Message to Agent

maestro-cli send a1b2c3 "Add error handling to the login endpoint"
Response: 
{
  "agentId": "a1b2c3d4-...",
  "agentName": "Backend Engineer",
  "sessionId": "sess_xyz",
  "response": "I've added comprehensive error handling...",
  "success": true,
  "usage": {
    "inputTokens": 1250,
    "outputTokens": 890,
    "totalCostUsd": 0.0045
  }
}

​
Command Categories

​
List Commands

Query agents, groups, playbooks, and sessions: 
maestro-cli list groups
maestro-cli list agents --group <id>
maestro-cli list playbooks --agent <id>
maestro-cli list sessions <agent-id>

​
Show Commands

Detailed information about specific resources: 
maestro-cli show agent <id>
maestro-cli show playbook <id>

​
Playbook Execution

Run playbooks with various options: 
maestro-cli playbook <id> [options]
​
--json
boolean
Output JSONL events for scripting
​
--dry-run
boolean
Preview execution without making changes
​
--no-history
boolean
Skip writing history entries
​
--wait
boolean
Wait for agent to become available if busy
​
--debug
boolean
Show detailed debug information
​
--verbose
boolean
Show full prompts sent to agents

​
Send Command

Direct agent messaging for one-off tasks: 
maestro-cli send <agent-id> <message> [options]
​
-s, --session
string
Resume existing session for multi-turn conversations

​
Clean Commands

Maintenance operations: 
maestro-cli clean playbooks --dry-run

​
Output Formats

All commands support two output modes:

​
Human-Readable (Default)

Colorful, formatted terminal output: 
maestro-cli list agents

​
JSON/JSONL (Scripting)

Machine-parseable structured data: 
maestro-cli list agents --json
maestro-cli playbook abc123 --json  # JSONL stream
Use --json flag on any command to get structured output suitable for parsing with jq, scripts, or other tools.

​
Agent ID Resolution

All commands support partial ID matching: 
# Full ID
maestro-cli show agent a1b2c3d4-5e6f-7g8h-9i0j-k1l2m3n4o5p6

# Partial ID (first 6+ chars)
maestro-cli show agent a1b2c3

# Also works for playbooks and groups
maestro-cli playbook abc
If the partial ID matches multiple resources, the CLI will show an error listing all matches. Provide more characters to uniquely identify the resource.

​
Exit Codes

The CLI uses standard exit codes:
  • 0 - Success
  • 1 - Error (check stderr for details)

​
Next Steps

CLI Commands

Complete reference for all commands and options

Automation Patterns

Workflows and patterns for automated agent orchestration

Scripting Guide

Parse JSONL output and integrate with your tools

Playbooks

Learn about Auto Run playbooks and batch execution

Build docs developers (and LLMs) love

Get started for freeTalk to us