docs: correct output format showcase examples

2026-04-08 13:50:55 +00:00
parent caa95e4ba1
commit 51757b6cc7
2 changed files with 37 additions and 36 deletions
@@ -4,8 +4,9 @@

 CleverAgents CLI supports six distinct output formats selectable via the global
 `--format` (or `-f`) flag. This lets you switch between human-friendly rich
-panels, machine-readable JSON/YAML, plain key-value text, ASCII tables, and
-ANSI-coloured output — all from the same commands. This example walks through
+panels, machine-readable JSON/YAML, plain key-value text, ASCII tables, and the
+legacy `color` flag (currently identical to `plain`) — all from the same
+commands. This example walks through
 every format using the `version`, `info`, `diagnostics`, and `actor list`
 commands.

@@ -16,8 +17,8 @@ commands.

 ## What You'll Learn

- How to use the **global** `--format` / `-f` flag (set once, applies to any
-  subcommand)
+- How to use the **global** `--format` / `-f` flag (set once for top-level
+  commands) and when to fall back to a **per-command** flag (e.g., `actor list`)
 - The six supported formats: `rich`, `json`, `yaml`, `plain`, `table`, `color`
 - The **JSON/YAML envelope** structure (`command`, `status`, `exit_code`,
  `data`, `timing`, `messages`)
@@ -38,7 +39,7 @@ $ agents --format json version
 **Expected Output:**
 ```json
 {
-  "command": "version",
+  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
@@ -62,7 +63,7 @@ $ agents --format json version
  "messages": [
    {
      "level": "ok",
-      "text": "version completed"
+      "text": "ok"
    }
  ]
 }
@@ -79,7 +80,7 @@ The output is wrapped in the **spec-required envelope**:

 | Field | Description |
 |---|---|
-| `command` | The CLI command that was run |
+| `command` | The CLI command that was run (empty for commands that don't set it explicitly) |
 | `status` | `"ok"`, `"warn"`, or `"error"` |
 | `exit_code` | `0` for success |
 | `data` | The command-specific payload |
@@ -96,7 +97,7 @@ $ agents --format yaml version

 **Expected Output:**
 ```yaml
-command: version
+command: ''
 status: ok
 exit_code: 0
 data:
@@ -116,7 +117,7 @@ timing:
  duration_ms: 2
 messages:
 - level: ok
-  text: version completed
+  text: ok
 ```

 **What's Happening:**
@@ -208,7 +209,7 @@ $ agents --format json info
  "messages": [
    {
      "level": "ok",
-      "text": "completed"
+      "text": "ok"
    }
  ]
 }
@@ -272,7 +273,7 @@ $ agents --format json diagnostics
  "messages": [
    {
      "level": "ok",
-      "text": "completed"
+      "text": "ok"
    }
  ]
 }
@@ -294,10 +295,10 @@ $ agents --format json diagnostics --check

 ---

-### Step 7: List actors with the `-f` shorthand
+### Step 7: List actors with the per-command flag

 ```bash
-$ agents -f json actor list
+$ agents actor list --format json
 ```

 **Expected Output:**
@@ -325,7 +326,7 @@ $ agents -f json actor list
  "messages": [
    {
      "level": "ok",
-      "text": "completed"
+      "text": "ok"
    }
  ]
 }
@@ -333,20 +334,17 @@ $ agents -f json actor list

 **What's Happening:**

-`actor list` uses the **same global `--format` flag** — the format is stored in
-`ctx.obj["format"]` by the root callback and read by the subcommand. The `data`
-field is a JSON array when the command returns a list of items.
-
-> **Note:** `actor list` also accepts a **per-command** `--format` / `-f` flag
-> for backward compatibility. The global flag takes precedence when both are
-> present.
+`actor list` defines its **own** `--format`/`-f` option. The global flag handled
+by the root `agents` command is not propagated here, so provide `--format` after
+the subcommand when you need structured output. The `data` field is a JSON array
+when the command returns a list of items.

 ---

 ### Step 8: List actors in YAML format

 ```bash
-$ agents -f yaml actor list
+$ agents actor list --format yaml
 ```

 **Expected Output:**
@@ -368,7 +366,7 @@ timing:
  duration_ms: 11
 messages:
 - level: ok
-  text: completed
+  text: ok
 ```

 ---
@@ -376,7 +374,7 @@ messages:
 ### Step 9: List actors in plain format

 ```bash
-$ agents -f plain actor list
+$ agents actor list --format plain
 ```

 **Expected Output:**
@@ -415,7 +413,7 @@ $ agents -f json diagnostics | jq '.data.has_errors'
 false

 # List all actor names
-$ agents -f json actor list | jq -r '.data[].name'
+$ agents actor list --format json | jq -r '.data[].name'
 anthropic/claude-sonnet-4-6

 # Get the timing for a command
@@ -437,7 +435,7 @@ $ agents -f json diagnostics | jq '.data.checks[] | select(.status == "warn")'
 | `yaml` | Yes | No | Config files, human-readable structured data |
 | `plain` | No | No | `grep`/`awk` pipelines, minimal terminals |
 | `table` | No | Box-drawing chars | Tabular data in terminals |
-| `color` | No | Yes (ANSI) | Coloured output without Rich panels |
+| `color` | No | No | Legacy alias for plain text output |

 ---

@@ -449,18 +447,21 @@ $ agents -f json diagnostics | jq '.data.checks[] | select(.status == "warn")'
 ```
 # 1. JSON version — envelope with data.version
 $ agents --format json version
-{"command": "version", "status": "ok", "exit_code": 0,
+{"command": "", "status": "ok", "exit_code": 0,
 "data": {"version": "1.0.0", "channel": "stable", ...},
- "timing": {"duration_ms": 3}, "messages": [{"level": "ok", "text": "version completed"}]}
+ "timing": {"duration_ms": 3}, "messages": [{"level": "ok", "text": "ok"}]}

 # 2. YAML version — same envelope, YAML syntax
 $ agents --format yaml version
-command: version
+command: ''
 status: ok
 exit_code: 0
 data:
  version: 1.0.0
  ...
+messages:
+- level: ok
+  text: ok

 # 3. Plain version — raw key:value, no envelope
 $ agents --format plain version
@@ -483,17 +484,17 @@ $ agents --format json diagnostics
 {"data": {"checks": [...], "summary": {"total": 11, "ok": 9, "warnings": 2, "errors": 0}}}

 # 7. JSON actor list — data is an array
-$ agents -f json actor list
+$ agents actor list --format json
 {"data": [{"name": "anthropic/claude-sonnet-4-6", "provider": "anthropic", ...}]}

 # 8. YAML actor list
-$ agents -f yaml actor list
+$ agents actor list --format yaml
 data:
 - name: anthropic/claude-sonnet-4-6
  ...

 # 9. Plain actor list — key:value per actor, --- separator between actors
-$ agents -f plain actor list
+$ agents actor list --format plain
 name: anthropic/claude-sonnet-4-6
 provider: anthropic
 ...
@@ -523,7 +524,7 @@ Now that you've seen all six output formats, try these variations:

 - **CI health check**: `agents -f json diagnostics --check && echo "All good"`
 - **Extract a field**: `agents -f json version | jq -r '.data.commit'`
- **Monitor actor count**: `agents -f json actor list | jq '.data | length'`
+- **Monitor actor count**: `agents actor list --format json | jq '.data | length'`
 - **YAML config snapshot**: `agents -f yaml info > system-snapshot.yaml`
 - **Plain grep**: `agents -f plain info | grep database`

@@ -12,9 +12,9 @@
        "agents -f json version",
        "agents --format json info",
        "agents --format json diagnostics",
-        "agents -f json actor list",
-        "agents -f yaml actor list",
-        "agents -f plain actor list"
+        "agents actor list --format json",
+        "agents actor list --format yaml",
+        "agents actor list --format plain"
      ],
      "complexity": "intermediate",
      "educational_value": "high",