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

# Output formats

> How the bronto CLI picks an output format, what table, json, jsonl, csv, and raw look like, and how --fields and --jq apply.

Data goes to stdout. Notices, progress, warnings, and errors go to stderr, so a pipe on
stdout carries only data. `--quiet` suppresses the notices.

## How the format is chosen

1. `-o`/`--output` on the command line.
2. The `output` setting from a project `.bronto.toml` or your profile.
3. Otherwise, based on where stdout goes:

| stdout | `search`, `tail`, `traces` | every other command |
| - | - | - |
| a terminal | `table` | `table` |
| a pipe or file | `jsonl` | `json` |

## Formats

| Format | Shape |
| - | - |
| `table` | Aligned columns with an uppercase header. Long cells are truncated. Prints `No results.` to stderr when empty. |
| `json` | One JSON document. Lists are an array, pretty-printed. |
| `jsonl` | One compact JSON object per line. |
| `csv` | A header row, then one row per record. A single record, such as `get` output, is one row; nested values are compact JSON cells. |
| `raw` | For events, the original `@raw` line. Other rows print as compact JSON. |

Commands that return one record rather than rows (`get`, `create`, `update`, `ping`, and
others) have no table layout: in `table` mode, including the terminal default, they print
the record as indented JSON.

JSON output doesn't escape `&`, `<`, and `>`, so URLs and queries print as written.

Use `jsonl` for streaming, since a consumer can process each line as it arrives. `json`
has to be parsed as a whole.

Numbers keep their exact value in `json`, `jsonl`, and `--jq` output. 64-bit ids such as
`metadata.sequence` aren't rounded to floats.

Some views render their own layout at a terminal instead of a table: the expanded view
(`search -x`), `--histogram`, `--patterns`, live `tail` aggregates, and the `traces show`
and `traces shape` waterfalls.

## Control characters

Log lines, resource names and API error messages can contain terminal escape sequences,
for example from a crafted user agent that ended up in a log. The table format, the views
above, `tail` lines and error messages print control characters as visible escapes such
as `\x1b` and `\r`, so they can't change your terminal's title, clear the screen or plant
hidden links. Newlines and tabs are kept in `tail` lines and become `\n` and `\t` in table
cells.

`json`, `jsonl`, `csv` and `raw` keep values byte-exact. JSON escapes control characters
itself. A CSV cell can start with `=`, `+`, `-` or `@`, which spreadsheet apps read as a
formula, so check the data before you open search results from untrusted sources in a
spreadsheet.

## --fields

`--fields a,b,c` keeps only the named keys in `json`, `jsonl`, and `csv`, and picks the
columns in `table` output for resource lists, `search`, and `tail`.

Resource lists add derived columns to `table` and `csv`, such as `created`, `modified`, and
`last_activity`. `json` and `jsonl` keep the raw API rows, but naming a derived column in
`--fields` selects it there too, with absolute timestamps as in `csv`.

`--fields '?'` prints the field names available instead of the data. For the streaming
commands (`tail`, `traces`), combine it with a machine format such as `-o jsonl`.

`search` flattens each event, and the fields parsed from the log line sit under
`message_kvs.`. `--fields` takes either form: a bare `status` finds `message_kvs.status`
when the event has no top-level `status` key, and the column or key is named the way you
typed it:

```console theme={"dark"}
$ bronto search "status >= 500" -d prod/checkout-service --since 1h -n 1 --fields '?'
@raw
@status
@time
message_kvs.duration_ms
message_kvs.host
message_kvs.message
message_kvs.path
message_kvs.service
message_kvs.status
message_kvs.trace_id
metadata.logId
metadata.origin
metadata.sequence
metadata.timestamp
$ bronto search "status >= 500" -d prod/checkout-service --since 1h -n 3 --fields '@time,host,status'
@TIME                        HOST   STATUS
2026-07-19 09:24:49.632 UTC  web-3  502
2026-07-19 09:24:33.007 UTC  web-3  502
2026-07-19 09:24:18.321 UTC  web-2  502
```

An exact key always wins over the `message_kvs.` fallback. A name that matches neither is
left out. The fallback applies only to names you pass to `--fields`; without it, each
column shows its exact key. `tail` asks the server for the fields you name, so it takes the same plain names.

`--fields` is rejected with `-o raw`, and with the `traces show` and `traces shape`
renderers.

## --jq

`--jq '<expr>'` applies a jq expression and prints each result on its own line.

* It needs `json` or `jsonl` output. At a terminal, pass `-o json` or `-o jsonl`; piped,
  the default formats already qualify.
* With `json` output of a list, the expression runs once per element.
* It runs after `--fields`. Without `--fields` it sees the full keys, such as
  `."message_kvs.host"` on a search event. With `--fields host` it sees only the output
  keys you requested, so write `.host`.
* A value that makes the expression fail is skipped. The other values still print. This
  differs from the `jq` CLI, which stops at the first error.
* Results print as compact JSON, so strings keep their quotes. `-r` (`--raw-output`)
  prints string results without quotes, like `jq -r`, and other values as compact JSON.
  It needs `--jq`.

```sh theme={"dark"}
bronto monitors list -o jsonl --jq '.name'
id="$(bronto monitors get "Payments latency p95" --jq .id -r)"
```

## -x / --expand

`bronto search -x` prints each event as a block of `key value` lines with every field,
untruncated. It works only with table output: with `-o json`, `jsonl`, `csv`, or `raw` it fails with a
usage error, because those formats already include every field. To get the expanded view
in a pipe, pass `-o table -x`.

## Color

Colors are on at a terminal and off otherwise. The order of precedence is `--no-color`,
then `NO_COLOR`, then `FORCE_COLOR`, then `TERM=dumb`, then whether stdout is a terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.