Overview The Maestro CLI provides command-line access to agents, playbooks, and batch processing. Perfect for automation, CI/CD pipelines, and scripting.
The CLI shares the same configuration as the desktop app, accessing your agents and playbooks from ~/.maestro.
Installation The CLI is included with Maestro:
# Check installation maestro-cli --version # View help maestro-cli --help
Commands List Resources View your agents, groups, playbooks, and sessions:
Groups
Agents
Playbooks
Sessions
# List all agent groups maestro-cli list groups # JSON output maestro-cli list groups --json
Show Details Get detailed information about resources:
# Show agent details and stats maestro-cli show agent < agent-i d > # JSON output maestro-cli show agent < agent-i d > --json
Run Playbook Execute saved playbooks:
# Run a playbook (supports partial IDs) maestro-cli playbook < playbook-i d > # Options: --dry-run # Preview without executing --no-history # Skip history logging --json # JSON output for parsing --debug # Show debug information --verbose # Show full prompts --wait # Wait if agent is busy
Playbook IDs support prefix matching. Use the first few characters if unambiguous.
Send Message Send a message to an agent:
# One-shot message maestro-cli send < agent-i d > "Your message here" # Continue conversation maestro-cli send < agent-i d > "Follow-up" --session < session-i d >
Clean Resources Remove orphaned data:
# Remove playbooks for deleted agents maestro-cli clean playbooks # Preview without deleting maestro-cli clean playbooks --dry-run # JSON output maestro-cli clean playbooks --json
Human Readable Default format for terminal use:
maestro-cli list agents ID Name Provider State abc123 My Agent claude-code ready def456 Test Agent codex busy ghi789 Remote Agent opencode ready
JSON Lines Machine-readable output for scripting:
maestro-cli list agents --json { "id" : "abc123" , "name" : "My Agent" , "toolType" : "claude-code" , "state" : "ready" } { "id" : "def456" , "name" : "Test Agent" , "toolType" : "codex" , "state" : "busy" } { "id" : "ghi789" , "name" : "Remote Agent" , "toolType" : "opencode" , "state" : "ready" }
Playbook Execution Event Streaming Playbooks emit events during execution:
{ "type" : "start" , "playbook" : "Update Docs" , "documents" : 5 , "timestamp" : 1234567890 } { "type" : "document_start" , "index" : 0 , "name" : "intro.md" , "timestamp" : 1234567891 } { "type" : "task_complete" , "task" : "Update introduction" , "timestamp" : 1234567892 } { "type" : "document_complete" , "index" : 0 , "duration" : 1250 , "timestamp" : 1234567893 } { "type" : "loop_start" , "iteration" : 1 , "timestamp" : 1234567894 } { "type" : "complete" , "totalDuration" : 5000 , "timestamp" : 1234567895 }
Wait Mode Handle busy agents gracefully:
Error Handling Properly handle errors in scripts:
#!/bin/bash set -e # Exit on error # Run playbook if maestro-cli playbook abc123 --json > output.jsonl 2>&1 ; then echo "Playbook completed successfully" # Process results jq -r 'select(.type=="complete") | .totalDuration' output.jsonl else echo "Playbook failed" # Extract error jq -r 'select(.type=="error") | .message' output.jsonl exit 1 fi
Integration Examples CI/CD Pipeline .github/workflows/docs.yml
name : Update Documentation on : push : branches : [ main ] jobs : update-docs : runs-on : ubuntu-latest steps : - uses : actions/checkout@v2 - name : Run documentation playbook run : | maestro-cli playbook doc-update-123 --json > results.jsonl - name : Check results run : | if jq -e 'select(.type=="error")' results.jsonl; then echo "Playbook failed" exit 1 fi - name : Commit changes run : | git config user.name "Maestro Bot" git config user.email "[email protected] " git add docs/ git commit -m "Update documentation via Maestro" git push
Scheduled Tasks # Run daily documentation update at 2 AM 0 2 * * * maestro-cli playbook daily-docs --wait --json >> /var/log/maestro.log 2>&1 # Weekly cleanup 0 0 * * 0 maestro-cli clean playbooks --json >> /var/log/maestro-clean.log 2>&1
Batch Processing Script #!/bin/bash # Update multiple playbooks in sequence PLAYBOOKS = ( "docs-intro" "docs-guides" "docs-api" ) for playbook in "${ PLAYBOOKS [ @ ]}" ; do echo "Running $playbook ..." if maestro-cli playbook " $playbook " --wait --json ; then echo "✓ $playbook completed" else echo "✗ $playbook failed" exit 1 fi done echo "All playbooks completed successfully"
Configuration Config Directory CLI uses the same config as desktop:
# macOS ~ /Library/Application Support/maestro/ # Linux ~ /.config/maestro/ # Windows %APPDATA%\maestro\
Storage Structure maestro/ ├── maestro-sessions.json # Agent configurations ├── playbooks/ │ ├── <agent-id>.json # Playbooks per agent │ └── ... └── history/ └── ... # Command history
Agent Detection CLI automatically detects installed agents:
# Checks for claude-code in PATH which claude-code
Ensure agent CLIs are in your PATH for CLI playbook execution.
Debugging Debug Mode # Show detailed execution information maestro-cli playbook abc123 --debug # Debug output includes: - Agent detection results - Spawn configuration - Process environment - Error stack traces
Verbose Mode # Show full prompts sent to agents maestro-cli playbook abc123 --verbose # Shows: - Complete system prompts - Template variable substitutions - Full document content
Exit Codes Code Meaning 0 Success 1 General error 2 Agent not found 3 Playbook not found 4 Agent busy 5 Agent CLI not installed