# Mastering Output Format Flags in CleverAgents CLI

## Overview

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
every format using the `version`, `info`, `diagnostics`, and `actor list`
commands.

## Prerequisites

- CleverAgents installed (`pip install cleveragents`)
- Python 3.13 or higher

## What You'll Learn

- How to use the **global** `--format` / `-f` flag (set once, applies to any
  subcommand)
- The six supported formats: `rich`, `json`, `yaml`, `plain`, `table`, `color`
- The **JSON/YAML envelope** structure (`command`, `status`, `exit_code`,
  `data`, `timing`, `messages`)
- How `plain` format differs — it renders raw key-value pairs without an
  envelope
- How to pipe JSON output into `jq` for scripting

---

## Step-by-Step Walkthrough

### Step 1: Check the version in JSON format

```bash
$ agents --format json version
```

**Expected Output:**
```json
{
  "command": "version",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "version": "1.0.0",
    "channel": "stable",
    "python": "3.13.9",
    "build_date": "2026-04-07",
    "commit": "43ab4a8f",
    "schema": "v3",
    "platform": "linux-x86_64",
    "dependencies": {
      "langgraph": "1.1.6",
      "langchain-core": "1.2.26",
      "pydantic": "2.12.5",
      "typer": "0.23.1"
    }
  },
  "timing": {
    "duration_ms": 3
  },
  "messages": [
    {
      "level": "ok",
      "text": "version completed"
    }
  ]
}
```

**What's Happening:**

The `--format json` flag is placed **before** the subcommand (`version`). This
is the global flag pattern — it is processed by the root `agents` callback and
stored in the Typer context so every subcommand can read it without needing its
own `--format` option.

The output is wrapped in the **spec-required envelope**:

| Field | Description |
|---|---|
| `command` | The CLI command that was run |
| `status` | `"ok"`, `"warn"`, or `"error"` |
| `exit_code` | `0` for success |
| `data` | The command-specific payload |
| `timing.duration_ms` | Elapsed time in milliseconds |
| `messages` | Human-readable status messages |

---

### Step 2: Check the version in YAML format

```bash
$ agents --format yaml version
```

**Expected Output:**
```yaml
command: version
status: ok
exit_code: 0
data:
  version: 1.0.0
  channel: stable
  python: 3.13.9
  build_date: '2026-04-07'
  commit: 43ab4a8f
  schema: v3
  platform: linux-x86_64
  dependencies:
    langgraph: 1.1.6
    langchain-core: 1.2.26
    pydantic: 2.12.5
    typer: 0.23.1
timing:
  duration_ms: 2
messages:
- level: ok
  text: version completed
```

**What's Happening:**

YAML format uses the same envelope structure as JSON but rendered as YAML.
Field ordering is preserved (not alphabetically sorted) because
`sort_keys=False` is passed to `yaml.dump`. This makes YAML output predictable
and diff-friendly.

---

### Step 3: Check the version in plain format

```bash
$ agents --format plain version
```

**Expected Output:**
```
version: 1.0.0
channel: stable
python: 3.13.9
build_date: 2026-04-07
commit: 43ab4a8f
schema: v3
platform: linux-x86_64
dependencies:
  langgraph: 1.1.6
  langchain-core: 1.2.26
  pydantic: 2.12.5
  typer: 0.23.1
```

**What's Happening:**

`plain` format is the exception — it renders the **raw data dict** directly as
`key: value` lines, **without** the JSON/YAML envelope. Nested dicts are
indented with two spaces. This is ideal for `grep`-based scripting or human
reading in terminals that don't support ANSI codes.

---

### Step 4: Use the shorthand `-f` flag

```bash
$ agents -f json version
```

**Expected Output:** *(identical to Step 1)*

**What's Happening:**

`-f` is the shorthand alias for `--format`. Both flags are equivalent and
interchangeable throughout the CLI.

---

### Step 5: Inspect system info in JSON format

```bash
$ agents --format json info
```

**Expected Output:**
```json
{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "version": "1.0.0",
    "data_dir": "/home/user/.cleveragents",
    "config_path": "/home/user/.cleveragents/config.toml",
    "database": "sqlite:////home/user/.cleveragents/cleveragents.db",
    "server_mode": "local",
    "platform": "Linux 6.1.0 (x86_64)",
    "automation": "semi",
    "providers_configured": 0,
    "providers": [],
    "debug_mode": false,
    "storage": {
      "db_size": "2.4 MB",
      "logs": "0.0 MB"
    }
  },
  "timing": {
    "duration_ms": 8
  },
  "messages": [
    {
      "level": "ok",
      "text": "completed"
    }
  ]
}
```

**What's Happening:**

The `info` command reports environment details: data directory, config path,
database URL, server mode, platform, automation profile, and storage sizes.
All sensitive values (API keys, secrets) are automatically redacted by the
`redact_dict` helper before rendering — you never accidentally leak credentials
in JSON output.

---

### Step 6: Run diagnostics in JSON format

```bash
$ agents --format json diagnostics
```

**Expected Output:**
```json
{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": {
    "checks": [
      {"name": "Config file", "status": "ok", "details": "not present (using defaults)"},
      {"name": "Data directory", "status": "ok", "details": "writable"},
      {"name": "Database", "status": "ok", "details": "writable"},
      {"name": "Openai key", "status": "warn", "details": "missing",
       "recommendation": "Set OPENAI_API_KEY to enable Openai models"},
      {"name": "Anthropic key", "status": "warn", "details": "missing",
       "recommendation": "Set ANTHROPIC_API_KEY to enable Anthropic models"},
      {"name": "Disk space", "status": "ok", "details": "42.3 GB free"},
      {"name": "File permissions", "status": "ok", "details": "data dir r/w"},
      {"name": "Git", "status": "ok", "details": "git 2.43.0"},
      {"name": "Stale locks", "status": "ok", "details": "0 stale locks"},
      {"name": "Async workers", "status": "ok", "details": "disabled (async.enabled=false)"},
      {"name": "Error Pattern DB", "status": "ok", "details": "empty (no patterns recorded)"}
    ],
    "summary": {
      "total": 11,
      "ok": 9,
      "warnings": 2,
      "errors": 0,
      "duration_s": 0.05
    },
    "recommendations": [
      "Set OPENAI_API_KEY to enable Openai models",
      "Set ANTHROPIC_API_KEY to enable Anthropic models"
    ],
    "has_errors": false,
    "has_warnings": true
  },
  "timing": {
    "duration_ms": 52
  },
  "messages": [
    {
      "level": "ok",
      "text": "completed"
    }
  ]
}
```

**What's Happening:**

`diagnostics` runs a suite of health checks and returns structured results.
Each check has a `name`, `status` (`ok`/`warn`/`error`), `details`, and an
optional `recommendation`. The `summary` block gives totals. The `has_errors`
boolean is useful for scripting: combine with `--check` to exit non-zero when
any check fails.

**Pro tip — exit non-zero on errors:**
```bash
$ agents --format json diagnostics --check
# exits 1 if any check has status "error"
```

---

### Step 7: List actors with the `-f` shorthand

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

**Expected Output:**
```json
{
  "command": "",
  "status": "ok",
  "exit_code": 0,
  "data": [
    {
      "name": "anthropic/claude-sonnet-4-6",
      "provider": "anthropic",
      "model": "claude-sonnet-4-6",
      "unsafe": false,
      "is_default": true,
      "is_built_in": true,
      "config_hash": "a1b2c3d4",
      "schema_version": "v3",
      "updated_at": "2026-04-07T08:00:00+00:00"
    }
  ],
  "timing": {
    "duration_ms": 12
  },
  "messages": [
    {
      "level": "ok",
      "text": "completed"
    }
  ]
}
```

**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.

---

### Step 8: List actors in YAML format

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

**Expected Output:**
```yaml
command: ''
status: ok
exit_code: 0
data:
- name: anthropic/claude-sonnet-4-6
  provider: anthropic
  model: claude-sonnet-4-6
  unsafe: false
  is_default: true
  is_built_in: true
  config_hash: a1b2c3d4
  schema_version: v3
  updated_at: '2026-04-07T08:00:00+00:00'
timing:
  duration_ms: 11
messages:
- level: ok
  text: completed
```

---

### Step 9: List actors in plain format

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

**Expected Output:**
```
name: anthropic/claude-sonnet-4-6
provider: anthropic
model: claude-sonnet-4-6
unsafe: False
is_default: True
is_built_in: True
config_hash: a1b2c3d4
schema_version: v3
updated_at: 2026-04-07T08:00:00+00:00
```

**What's Happening:**

For lists, `plain` format renders each item as a block of `key: value` lines.
Multiple items are separated by `---` (YAML-style document separator). This
makes it easy to process with `grep`, `awk`, or `sed`.

---

## Scripting with JSON Output

Because JSON output is clean and envelope-wrapped, it integrates naturally with
`jq`:

```bash
# Extract just the version number
$ agents -f json version | jq -r '.data.version'
1.0.0

# Check if any diagnostic errors exist
$ agents -f json diagnostics | jq '.data.has_errors'
false

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

# Get the timing for a command
$ agents -f json diagnostics | jq '.timing.duration_ms'
52

# Filter diagnostics to only warnings
$ agents -f json diagnostics | jq '.data.checks[] | select(.status == "warn")'
```

---

## Format Comparison Table

| Format | Envelope? | ANSI Codes? | Best For |
|--------|-----------|-------------|----------|
| `rich` | No | Yes (Rich panels) | Interactive terminal use |
| `json` | Yes | No | Scripting, APIs, `jq` |
| `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 |

---

## Complete Interaction Log

<details>
<summary>Click to see the full verified command sequence</summary>

```
# 1. JSON version — envelope with data.version
$ agents --format json version
{"command": "version", "status": "ok", "exit_code": 0,
 "data": {"version": "1.0.0", "channel": "stable", ...},
 "timing": {"duration_ms": 3}, "messages": [{"level": "ok", "text": "version completed"}]}

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

# 3. Plain version — raw key:value, no envelope
$ agents --format plain version
version: 1.0.0
channel: stable
python: 3.13.9
...

# 4. Shorthand -f flag
$ agents -f json version
# identical to --format json

# 5. JSON info — environment details
$ agents --format json info
{"command": "", "status": "ok", "exit_code": 0,
 "data": {"version": "1.0.0", "data_dir": "...", "database": "sqlite:///...", ...}}

# 6. JSON diagnostics — health checks array
$ 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
{"data": [{"name": "anthropic/claude-sonnet-4-6", "provider": "anthropic", ...}]}

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

# 9. Plain actor list — key:value per actor, --- separator between actors
$ agents -f plain actor list
name: anthropic/claude-sonnet-4-6
provider: anthropic
...
```
</details>

---

## Key Takeaways

- **`--format` is a global flag** — place it before the subcommand to apply to
  any command in the CLI.
- **`-f` is the shorthand** — `agents -f json version` is identical to
  `agents --format json version`.
- **JSON and YAML use an envelope** — the actual payload is always in the
  `data` field; `status`, `exit_code`, `timing`, and `messages` are metadata.
- **`plain` skips the envelope** — it renders raw `key: value` pairs, ideal
  for shell pipelines.
- **Secrets are always redacted** — sensitive values are masked before
  rendering regardless of format.
- **`diagnostics --check`** exits non-zero when errors are found — combine
  with `--format json` for CI integration.

## Try It Yourself

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'`
- **YAML config snapshot**: `agents -f yaml info > system-snapshot.yaml`
- **Plain grep**: `agents -f plain info | grep database`

## Related Examples

- See `docs/showcase/cli-tools/` for more CLI tool examples
- See `docs/showcase/api-clients/` for API integration patterns

---
*This example was automatically generated and verified by the CleverAgents UAT system.*
*Feature area: Output formats JSON YAML plain | Test cycle: 1 | Generated: 2026-04-07*