From caa95e4ba1f95e35bb356b7c8de5c741d0515c82 Mon Sep 17 00:00:00 2001 From: HAL 9000 Date: Tue, 7 Apr 2026 09:06:48 +0000 Subject: [PATCH 1/2] docs: update examples.json index with output format flags showcase --- docs/showcase/examples.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/showcase/examples.json b/docs/showcase/examples.json index a9f1908f0..1b8fa3b13 100644 --- a/docs/showcase/examples.json +++ b/docs/showcase/examples.json @@ -77,7 +77,7 @@ "keywords": ["CLI", "command-line", "terminal", "console", "tool"] }, "api-clients": { - "name": "API Clients", + "name": "API Clients", "description": "Command-line clients for web APIs", "keywords": ["API", "REST", "client", "HTTP", "web", "request"] }, @@ -92,5 +92,5 @@ "keywords": ["test", "pytest", "behave", "unittest", "automation", "QA"] } }, - "last_updated": null + "last_updated": "2026-04-07" } -- 2.52.0 From 51757b6cc7c4ed4ad00bfc0faf9d76347d4b89fe Mon Sep 17 00:00:00 2001 From: CleverThis Date: Wed, 8 Apr 2026 13:50:55 +0000 Subject: [PATCH 2/2] docs: correct output format showcase examples --- .../showcase/cli-tools/output-format-flags.md | 67 ++++++++++--------- docs/showcase/examples.json | 6 +- 2 files changed, 37 insertions(+), 36 deletions(-) diff --git a/docs/showcase/cli-tools/output-format-flags.md b/docs/showcase/cli-tools/output-format-flags.md index 28c892682..8c4a5e617 100644 --- a/docs/showcase/cli-tools/output-format-flags.md +++ b/docs/showcase/cli-tools/output-format-flags.md @@ -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` diff --git a/docs/showcase/examples.json b/docs/showcase/examples.json index 1b8fa3b13..0ff0fc6ee 100644 --- a/docs/showcase/examples.json +++ b/docs/showcase/examples.json @@ -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", -- 2.52.0