> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Output Formats

> The --output flag — table, json, yaml, ids. Sparkline columns for test-run history. Pipe-friendly modes for jq, yq, and shell scripting.

# Output formats

Every CLI command accepts `--output <format>`. The CLI auto-detects:

* **TTY** (your terminal) → `table` by default
* **Non-TTY** (pipe, CI) → `json` by default

Override with `--output` or with the `ROBOTICKS_OUTPUT` env var.

## Supported formats

| Format  | When to use                                                  |
| ------- | ------------------------------------------------------------ |
| `table` | Human reading in a terminal                                  |
| `json`  | Anything machine-readable; piping into `jq`                  |
| `yaml`  | Config-style dumps; piping into `yq`; copy-paste into commit |
| `ids`   | One ID per line for `xargs`/`for` loops (list commands only) |
| `csv`   | Spreadsheet ingestion (list and matrix commands only)        |

## Examples

### Table (default for TTY)

```bash theme={null}
rbtk test list
```

```
RUN ID    BRANCH         STATUS  TESTS         DURATION   STARTED            POOL
8a1f...   main           PASS    412/412       2m 14s     12 min ago         prod-gpu-farm
8a1c...   pr/214         FAIL    411/412       2m 19s     22 min ago         prod-gpu-farm
```

The `table` renderer is responsive — column widths adapt to terminal width, long values truncate with `…` and become available in `--output json` for the full string.

### Sparkline column

`rbtk test list --branch <ref>` adds a **sparkline** of the last 20 runs on that branch:

```bash theme={null}
rbtk test list --branch main
```

```
RUN ID    BRANCH    LAST 20         STATUS  TESTS      DURATION
8a1f...   main      ▁▂▂▁▁▂▂▃▂▂▁▁▂▁▁▁▁▁▁▁  PASS    412/412    2m 14s
8a1c...   main      ▁▂▂▁▁▂▂▃▂▂▁▁▂▁▁▁▁▁▁   PASS    412/412    2m 11s
```

Each spark represents one prior run's failed-test count. Reading left-to-right: oldest → newest. Tall sparks = bad runs. The sparkline is also available on:

* `rbtk requirements list` — per-requirement, last 20 runs' confirmation status
* `rbtk pool stats --since 24h` — queue wait p95 over the window

Disable with `--no-sparkline` if you pipe `table` output (rare).

### JSON

```bash theme={null}
rbtk test list --output json | jq '.[0]'
```

```json theme={null}
{
  "id": "8a1f3c2d-...",
  "branch": "main",
  "git_sha": "abcdef123456",
  "status": "passed",
  "tests": { "total": 412, "passed": 412, "failed": 0, "skipped": 0 },
  "duration_seconds": 134,
  "started_at": "2026-05-24T12:42:01Z",
  "completed_at": "2026-05-24T12:44:15Z",
  "pool": { "name": "prod-gpu-farm", "type": "self-hosted" },
  "requirement_coverage": {
    "confirmed": 142, "uncovered": 18, "total": 160,
    "delta_vs_previous": { "confirmed": 3, "uncovered": -1, "stale": 0 }
  },
  "links": {
    "self": "https://app.roboticks.io/r/warehouse/runs/8a1f3c2d",
    "evidence_pack": "https://api.roboticks.io/v1/runs/8a1f3c2d/evidence-pack"
  }
}
```

JSON output is **schema-stable** across point releases of the CLI. Breaking changes are gated behind a new CLI major version.

### YAML

```bash theme={null}
rbtk requirements list --output yaml > reqs.yaml
```

YAML preserves field ordering and is friendly to commit as a snapshot.

### IDs-only

```bash theme={null}
rbtk test list --output ids
# 8a1f3c2d
# 8a1c0411
# 8a1a72e0
```

Useful for shell loops:

```bash theme={null}
rbtk test list --status failed --since 7d --output ids \
  | xargs -I{} rbtk test logs {} --tail 50
```

### CSV

```bash theme={null}
rbtk requirements coverage --format matrix --output csv > coverage-matrix.csv
```

Open in Excel / Numbers / Google Sheets without import gymnastics.

## Piping patterns

### `jq` for fields

```bash theme={null}
# Get the IDs of all failed runs in the last 24h
rbtk test list --status failed --since 24h --output json | jq -r '.[].id'

# Get the requirement IDs uncovered on main
rbtk requirements coverage --filter uncovered --output json \
  | jq -r '.requirements[].id'
```

### `yq` for YAML

```bash theme={null}
# Subset a YAML dump
rbtk requirements list --output yaml \
  | yq '.[] | select(.type == "safety")'
```

### Watch loops

```bash theme={null}
watch -n 10 'rbtk pool runners --pool prod-gpu-farm'
```

Or use the built-in `--watch` on commands that support it:

```bash theme={null}
rbtk pool runners --pool prod-gpu-farm --watch
rbtk test list --watch
```

`--watch` keeps the table view alive and re-renders on change (server-sent events for low latency).

## Environment overrides

| Variable                      | Equivalent flag  |
| ----------------------------- | ---------------- |
| `ROBOTICKS_OUTPUT`            | `--output`       |
| `NO_COLOR=1`                  | `--no-color`     |
| `ROBOTICKS_QUIET=true`        | `--quiet`        |
| `ROBOTICKS_NO_SPARKLINE=true` | `--no-sparkline` |

`ROBOTICKS_OUTPUT=json` is what GitHub Actions / GitLab CI / Jenkins jobs typically set globally so every command in the pipeline emits JSON.

## Determinism guarantees

| Format  | Stable across CLI versions?                              |
| ------- | -------------------------------------------------------- |
| `json`  | Yes (field names and types pinned to CLI major version)  |
| `yaml`  | Yes (mirror of `json`)                                   |
| `csv`   | Headers stable; row order matches `json`                 |
| `table` | **No** — column widths and trailing whitespace may shift |
| `ids`   | Yes                                                      |

Scripts and CI parsers should use `json` (or `ids`/`csv`). Do not parse `table`.

## Next

<CardGroup cols={2}>
  <Card title="Test commands" icon="flask-vial" href="/cli/test-commands">
    See sparkline tables in action.
  </Card>

  <Card title="CI/CD recipes" icon="code-branch" href="/cli/ci-cd">
    Pipe `json` output into pipeline steps.
  </Card>
</CardGroup>