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

# Formatar e filtrar saída

> Alterne o mka1 CLI entre saída pretty, JSON, YAML, tabela e TOON. Transforme resultados com jq, faça streaming de eventos SSE e controle as cores.

Todo comando suporta `--output-format` para controlar como os resultados são exibidos no stdout:

| Formato | Flag                              | Quando usar                                                                                                                                                           |
| ------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pretty  | `--output-format pretty` (padrão) | Para ler a saída em um terminal. Pares chave-valor alinhados com cor e indentação aninhada.                                                                           |
| JSON    | `--output-format json`            | Para scripts, uso com `jq`, salvar em arquivo. Mantém a ordem original dos campos e precisão numérica quando a resposta já é JSON.                                    |
| YAML    | `--output-format yaml`            | Saída semelhante a configuração, fácil de comparar visualmente.                                                                                                       |
| Tabela  | `--output-format table`           | Respostas em array onde cada item tem a mesma estrutura — ex: `llm models list`.                                                                                      |
| TOON    | `--output-format toon`            | [Token-Oriented Object Notation](https://github.com/toon-format/spec). Compacto, orientado a linhas, 30–60% menos tokens que JSON — ideal para uso em prompts de LLM. |

```bash theme={null}
# Padrão legível para humanos
mka1 llm models list

# JSON legível para máquinas
mka1 llm models list --output-format json

# TOON compacto para passar para outro LLM
mka1 llm responses get --response-id resp_123 --output-format toon
```

## Filtrar e transformar com jq

Use `--jq` para filtrar ou remodelar respostas em linha com uma expressão [jq](https://jqlang.org). Isso sempre gera JSON e sobrescreve o `--output-format`:

```bash theme={null}
# Extrair um único campo
mka1 llm models list --jq '.data[].id'

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

# Remodelar em um novo objeto
mka1 llm files list --jq '.data[] | {id, name: .filename, bytes}'
```

Como `--jq` imprime JSON puro, ele compõe bem com shells e outros comandos CLI:

```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 {}
```

## Paginação e streaming

Algumas operações retornam muitos itens ou eventos enviados pelo servidor. A saída é escrita incrementalmente à medida que cada item chega:

| Formato           | Comportamento de streaming                                                          |
| ----------------- | ----------------------------------------------------------------------------------- |
| `json`            | Um objeto JSON compacto por linha ([NDJSON](https://github.com/ndjson/ndjson-spec)) |
| `yaml`            | Documentos YAML separados por `---`                                                 |
| `toon`            | Um objeto codificado em TOON por bloco, separados por linhas em branco              |
| `pretty` (padrão) | Itens formatados separados por linhas em branco                                     |

### Paginar por uma coleção

Passe `--all` em comandos de listagem para seguir automaticamente o cursor `next` e emitir cada página conforme ela chega:

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

### Fazer streaming de eventos enviados pelo servidor

Operações de streaming (por exemplo, `llm responses create --stream`) emitem um evento por linha:

```bash theme={null}
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Escreva três tópicos de notas de lançamento."' \
  --stream \
  --output-format json

# Manter apenas deltas de texto
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Escreva três tópicos de notas de lançamento."' \
  --stream \
  --jq 'select(.type == "response.output_text.delta") | .delta'
```

Pressione `Ctrl+C` para parar de consumir o stream antes do fim.

## Cor

`--color` controla as cores do terminal para o formato `pretty`:

| Valor           | Comportamento                                                   |
| --------------- | --------------------------------------------------------------- |
| `auto` (padrão) | Usa cor quando o stdout é um TTY, texto simples caso contrário. |
| `always`        | Sempre usa cor.                                                 |
| `never`         | Nunca usa cor.                                                  |

O CLI também respeita as variáveis de ambiente amplamente usadas [`NO_COLOR`](https://no-color.org/) e `FORCE_COLOR`.

## Incluir cabeçalhos da resposta

Use `--include-headers` quando precisar dos cabeçalhos HTTP da resposta junto com o corpo — por exemplo, para ler um ID de requisição para suporte ou inspecionar um cabeçalho de limite de taxa:

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

## Escrever respostas binárias em um arquivo

Comandos que retornam dados binários (como `llm speech speak`) suportam `--output-file` para gravar o corpo em um caminho sem poluir o stdout:

```bash theme={null}
mka1 llm speech speak \
  --text 'Olá, bem-vindo ao nosso serviço.' \
  --output-file ./welcome.wav
```

Use `--output-b64` quando precisar embutir o payload binário em um pipeline de JSON ou texto.

## Códigos de saída

| Código de saída | Significado                          |
| --------------- | ------------------------------------ |
| `0`             | Sucesso. Resposta escrita no stdout. |
| `1`             | Erro. Detalhes escritos no stderr.   |

Isso torna o fluxo de controle estilo `if` simples em scripts:

```bash theme={null}
if ! mka1 llm responses get --response-id resp_123 > out.json 2> err.log; then
  echo "Requisição falhou — veja err.log"
  exit 1
fi
```

Veja [debug e inspeção](/pt/docs/cli/diagnostics) para `--dry-run` e `--debug`, que oferecem mais visibilidade sobre por que um comando falhou.