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

# Output formats & schema

Every command supports four output formats and a small projection toolbox:

* **`--output json`** (default) — pretty-printed JSON, colored on a TTY.
* **`--output yaml`** — YAML, useful for hand-editing.
* **`--output jsonl`** — one JSON object per line, ideal for streaming and `jq`.
* **`--output table`** — fixed-width ASCII table.

Plus orthogonal modifiers:

* **`--columns a,b,c`** — keep only the listed dot-paths (works for `json` / `yaml` / `jsonl` / `table`).
* **`--cell-max <N>`** — truncate table cells; default 28, `0` disables truncation entirely.
* **`--embed <token>`** — pull related entities/values into `_embedded` per spec-defined token.
* **`--schema`** — emit the JSON Schema for the command instead of running it.

## Choosing a format

```bash theme={"system"}
bron tx list --output json     # default
bron tx list --output yaml
bron tx list --output jsonl    # one record per line — pipe-friendly
bron tx list --output table    # ASCII grid, *At fields render as ISO UTC, nested objects collapse to {…}/[…N]
```

`json` is colored when stdout is a TTY. Disable with `NO_COLOR=1`, force on with `FORCE_COLOR=1`.

## Projecting fields with `--columns`

`--columns` accepts a comma-separated list of dot-paths. The command keeps only those keys, in the listed order. Works for every format:

```bash theme={"system"}
# Table view of just the columns you care about.
bron tx list --output table \
  --columns transactionId,status,transactionType,createdAt

# Same projection, but as JSON.
bron tx list --output json \
  --columns transactionId,status,params.amount

# Dot-paths drill into nested objects (table flattens, json/yaml/jsonl emit nested).
bron tx list --output table \
  --columns transactionId,params.amount,params.assetId,_embedded.asset.symbol
```

For a list endpoint, `--columns` projects each item in the list (e.g. each transaction). For a single resource it projects the top-level object. A dot-path that crosses an array applies to every element — `--columns transactionId,_embedded.events.usdAmount` keeps `usdAmount` on each event of each transaction.

<Note>
  In the [MCP server](/sdk/cli/mcp), the same projection is the `fields` tool argument, and heavier transforms are the `jq` argument — applied server-side so the trimmed result is all the agent's context ever sees. There's no shell to pipe through, so the shaping moves into the call itself.
</Note>

## Filtering and transforming — pipe to `jq`

The CLI keeps output shaping minimal on purpose: `--columns` for projection, `--output jsonl` for line-based piping, and then `jq` for everything heavier (`select`, slicing, arithmetic, joins). One mental model, one tool to learn:

```bash theme={"system"}
bron tx list --output jsonl \
  | jq 'select(.status == "signed") | .transactionId'

bron balances list --embed prices --output jsonl \
  | jq -s 'map(._embedded.usdValue | tonumber) | add'
```

## Date and number handling

* **Decimals stay strings end-to-end** (`"0.0000123"`) — no `float64` rounding, no precision loss. Don't unmarshal them as `Number` in your scripts.
* **Date fields render as ISO 8601 UTC** in every format (`2026-04-30T11:14:13.274Z`), regardless of how the spec encodes them on the wire (epoch millis vs ISO).
* **Date-shaped query parameters** (names ending in `AtFrom`, `AtTo`, `Since`, `Before`, `After`) accept both ISO 8601 (`2026-04-01T00:00:00Z`, `2026-04-01`) and millisecond-epoch integers — the CLI normalises to millis before sending.

## `--embed` for related entities

Some list endpoints expose `--embed <token>` to fold related data into the response under `_embedded`, saving you a follow-up query. The available tokens depend on the resource:

```bash theme={"system"}
# Add USD prices and computed values to every balance.
bron balances list --embed prices \
  --output table --columns symbol,totalBalance,_embedded.usdPrice,_embedded.usdValue

# Resolve assetId on each transaction into _embedded.asset.
bron tx list --embed assets \
  --output table --columns transactionId,_embedded.asset.symbol,params.amount,status
```

Token discovery: `bron <r> <v> --help` lists the supported `--embed` values for that command. Internally each token routes to the matching backend `includeXxx` query parameter.

`_embedded` follows the HATEOAS pattern — it's an opt-in extra layer on top of the spec-defined response shape. A consumer that didn't ask for an embed never sees the extra keys, so generated SDK types stay aligned with the published schema.

<Note>
  In `--schema` the field is named `embedded`, but it serialises as `_embedded` on the wire — so a `--columns` (or MCP `fields` / `jq`) path must use the underscore: `_embedded.usdValue`, not `embedded.usdValue`. The MCP `bron_help` tool already prints the wire name.
</Note>

## `--schema` for machine consumers

`--schema` emits the JSON Schema for any command — request body, query params, response shape, every documented status code:

```bash theme={"system"}
bron --schema                            # full CLI as one OpenAPI 3.1 document
bron <resource> <verb> --schema          # single-command fragment
bron help --schema                       # alias for the full schema dump
bron --output yaml <r> <v> --schema      # same dump in YAML
```

`--schema` is strict OpenAPI 3.1. Pipe it to `jq`, `swagger-cli`, or any spec consumer.

For LLM agents this is the canonical entry point: one call to discover every command, every flag's type and `enum` values, and every response field. See [LLM agent integration](/sdk/cli/agents) for the full agent flow.

## Pipelines with `jq`

JSONL is the easiest format for shell pipelines. Combine it with `jq` for ad-hoc transformations:

```bash theme={"system"}
# Count transactions by status over the last day.
bron tx list --createdAtFrom "$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ)" --output jsonl \
  | jq -r '.status' | sort | uniq -c

# Pluck transaction IDs of every withdrawal awaiting approval.
bron tx list --transactionStatuses waiting-approval --transactionTypes withdrawal --output jsonl \
  | jq -r '.transactionId'

# Stream live updates and react in shell.
bron tx subscribe --transactionStatuses signing-required \
  | jq -r 'select(.transactionType == "withdrawal") | .transactionId' \
  | xargs -I {} bron tx approve {}
```

The CLI also accepts machine-readable input on stdin where it makes sense — `bron tx withdrawal --file -` reads a JSON body from stdin, useful for scripting or piping from another tool.