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

# Format and filter output

> Switch the mka1 CLI between pretty, JSON, YAML, table, and TOON output. Transform results with jq, stream SSE events, and control color.

Every command supports `--output-format` to control how results are rendered to stdout:

| Format | Flag                               | When to use                                                                                                                                                             |
| ------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pretty | `--output-format pretty` (default) | Reading output in a terminal. Aligned key-value pairs with color and nested indentation.                                                                                |
| JSON   | `--output-format json`             | Scripting, piping into `jq`, saving to a file. Passes through original field order and numeric precision when the response is already JSON.                             |
| YAML   | `--output-format yaml`             | Human-diffable configuration-like output.                                                                                                                               |
| Table  | `--output-format table`            | Array responses where each item has the same shape — e.g. `llm models list`.                                                                                            |
| TOON   | `--output-format toon`             | [Token-Oriented Object Notation](https://github.com/toon-format/spec). Compact, line-oriented, 30–60% fewer tokens than JSON — well-suited for piping into LLM prompts. |

```bash theme={null}
# Human-readable default
mka1 llm models list

# Machine-readable JSON
mka1 llm models list --output-format json

# Compact TOON for passing into another LLM
mka1 llm responses get --response-id resp_123 --output-format toon
```

## Filter and transform with jq

Use `--jq` to filter or reshape responses inline with a [jq](https://jqlang.org) expression. This always outputs JSON and overrides `--output-format`:

```bash theme={null}
# Extract a single field
mka1 llm models list --jq '.data[].id'

# Filter an array
mka1 llm responses list --jq '.data[] | select(.status == "completed")'

# Reshape into a new object
mka1 llm files list --jq '.data[] | {id, name: .filename, bytes}'
```

Because `--jq` prints plain JSON, it composes well with shells and with other CLI calls:

```bash theme={null}
mka1 llm files upload --file ./doc.pdf --purpose assistants --jq '.id' \
  | xargs -I {} mka1 llm vector-stores create-file --vector-store-id vs_123 --file-id {}
```

## Pagination and streaming

Some operations return many items or server-sent events. Output is written incrementally as each item arrives:

| Format             | Streaming behavior                                                                 |
| ------------------ | ---------------------------------------------------------------------------------- |
| `json`             | One compact JSON object per line ([NDJSON](https://github.com/ndjson/ndjson-spec)) |
| `yaml`             | YAML documents separated by `---`                                                  |
| `toon`             | One TOON-encoded object per block, separated by blank lines                        |
| `pretty` (default) | Pretty-printed items separated by blank lines                                      |

### Paginate through a collection

Pass `--all` on list commands to follow the `next` cursor automatically and emit every page as it arrives:

```bash theme={null}
mka1 llm responses list --all --output-format json > responses.ndjson
```

### Stream server-sent events

Streaming operations (for example, `llm responses create --stream`) emit one event per line:

```bash theme={null}
mka1 llm responses create \
  --model auto \
  --input '"Write three release-notes bullets."' \
  --stream \
  --output-format json

# Only keep text deltas
mka1 llm responses create \
  --model auto \
  --input '"Write three release-notes bullets."' \
  --stream \
  --jq 'select(.type == "response.output_text.delta") | .delta'
```

Press `Ctrl+C` to stop consuming a stream early.

## Color

`--color` controls terminal colors for the `pretty` format:

| Value            | Behavior                                             |
| ---------------- | ---------------------------------------------------- |
| `auto` (default) | Colorize when stdout is a TTY, plain text otherwise. |
| `always`         | Always colorize.                                     |
| `never`          | Never colorize.                                      |

The CLI also respects the widely used [`NO_COLOR`](https://no-color.org/) and `FORCE_COLOR` environment variables.

## Include response headers

Use `--include-headers` when you need the HTTP response headers alongside the body — for example, to read a request ID for support or inspect a rate-limit header:

```bash theme={null}
mka1 llm models list --include-headers
```

## Write binary responses to a file

Commands that return binary data (such as `llm speech speak`) support `--output-file` to write the body to a path without polluting stdout:

```bash theme={null}
mka1 llm speech speak \
  --text 'Hello, welcome to our service.' \
  --output-file ./welcome.wav
```

Use `--output-b64` instead when you need to embed the binary payload in a JSON or text pipeline.

## Exit codes

| Exit code | Meaning                              |
| --------- | ------------------------------------ |
| `0`       | Success. Response written to stdout. |
| `1`       | Error. Details written to stderr.    |

This makes `if`-style control flow straightforward in scripts:

```bash theme={null}
if ! mka1 llm responses get --response-id resp_123 > out.json 2> err.log; then
  echo "Request failed — see err.log"
  exit 1
fi
```

See [debug and inspect](/docs/cli/diagnostics) for `--dry-run` and `--debug`, which give you more visibility into why a command failed.