From df29ed91576b618192ebc857beb91ff572e5f1e0 Mon Sep 17 00:00:00 2001
From: Pedram Amini <pedram.amini@gmail.com>
Date: Sun, 11 Jan 2026 05:17:07 -0600
Subject: [PATCH] MAESTRO: Fix CLI documentation accuracy issues

- Added short flags -g (list agents) and -a (list playbooks) that were
  missing from documentation but exist in implementation
- Documented the clean playbooks command with --dry-run option (was
  completely undocumented)
- Clarified that list agents --json outputs a JSON array, not JSONL
  (different from other list commands)
- Updated JSON event examples to include missing fields: collapsed in
  group events, document in document_complete events
- Added loop_complete event type in JSON output examples
- Added success, usageStats, and totalCost fields to JSON examples
---
 docs/cli.md | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/docs/cli.md b/docs/cli.md
index b4535ce6..2858e8d8 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -38,6 +38,7 @@ maestro-cli list groups
 
 # List all agents
 maestro-cli list agents
+maestro-cli list agents -g <group-id>
 maestro-cli list agents --group <group-id>
 
 # Show agent details (history, usage stats, cost)
@@ -45,6 +46,7 @@ maestro-cli show agent <agent-id>
 
 # List all playbooks (or filter by agent)
 maestro-cli list playbooks
+maestro-cli list playbooks -a <agent-id>
 maestro-cli list playbooks --agent <agent-id>
 
 # Show playbook details
@@ -64,6 +66,10 @@ maestro-cli playbook <playbook-id> --wait --verbose
 
 # Debug mode for troubleshooting
 maestro-cli playbook <playbook-id> --debug
+
+# Clean orphaned playbooks (for deleted sessions)
+maestro-cli clean playbooks
+maestro-cli clean playbooks --dry-run
 ```
 
 ## JSON Output
@@ -82,17 +88,22 @@ GROUPS (2)
 
 # JSON output for scripting
 maestro-cli list groups --json
-{"type":"group","id":"group-abc123","name":"Frontend","emoji":"🎨","timestamp":...}
-{"type":"group","id":"group-def456","name":"Backend","emoji":"⚙️","timestamp":...}
+{"type":"group","id":"group-abc123","name":"Frontend","emoji":"🎨","collapsed":false,"timestamp":...}
+{"type":"group","id":"group-def456","name":"Backend","emoji":"⚙️","collapsed":false,"timestamp":...}
+
+# Note: list agents outputs a JSON array (not JSONL)
+maestro-cli list agents --json
+[{"id":"agent-abc123","name":"My Agent","toolType":"claude-code","cwd":"/path/to/project",...}]
 
 # Running a playbook with JSON streams events
 maestro-cli playbook <playbook-id> --json
 {"type":"start","timestamp":...,"playbook":{...}}
 {"type":"document_start","timestamp":...,"document":"tasks.md","taskCount":5}
 {"type":"task_start","timestamp":...,"taskIndex":0}
-{"type":"task_complete","timestamp":...,"success":true,"summary":"...","elapsedMs":8000}
-{"type":"document_complete","timestamp":...,"tasksCompleted":5}
-{"type":"complete","timestamp":...,"totalTasksCompleted":5,"totalElapsedMs":60000}
+{"type":"task_complete","timestamp":...,"success":true,"summary":"...","elapsedMs":8000,"usageStats":{...}}
+{"type":"document_complete","timestamp":...,"document":"tasks.md","tasksCompleted":5}
+{"type":"loop_complete","timestamp":...,"iteration":1,"tasksCompleted":5,"elapsedMs":60000}
+{"type":"complete","timestamp":...,"success":true,"totalTasksCompleted":5,"totalElapsedMs":60000,"totalCost":0.05}
 ```
 
 ## Scheduling with Cron