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

# Output and filtering

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


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