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

# Saída JSON

> Como ler a saída estruturada da CLI da Zapster a partir de scripts e agentes.

Toda invocação da CLI aceita a flag global `--json`. Com ela, a saída é um único objeto JSON por linha, no envelope:

```json theme={null}
{ "ok": true, "data": <payload> }
```

ou, em erro:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "invalid_token",
    "message": "Token is invalid",
    "hint": "Run `zapsterapi auth login --token <token>` first.",
    "details": { "status": 401 }
  }
}
```

A saída de sucesso vai para `stdout`. A saída de erro vai para `stderr` e o exit code é `1` (ou `2` para erros de uso, como flag desconhecida).

## Exemplos

### Listar instâncias e pegar o primeiro ID

```bash theme={null}
zapsterapi instance list --json | jq -r '.data.rows[0].id'
```

### Validar token em script

```bash theme={null}
if zapsterapi auth whoami --json > /dev/null 2>&1; then
  echo "ok"
else
  echo "token inválido"
fi
```

### Reagir ao código de erro

```bash theme={null}
output=$(zapsterapi message send --recipient 5511999999999 --text "oi" --json 2>&1)
code=$(echo "$output" | jq -r '.error.code // empty')
case "$code" in
  invalid_token) echo "renove o token";;
  invalid_recipient) echo "número errado";;
  "") echo "enviado";;
  *) echo "erro: $code";;
esac
```

## Garantias de estabilidade

* O envelope (`ok`, `data`, `error`) é estável dentro da major version `0.x` da CLI.
* Os campos dentro de `data` espelham a resposta da REST API correspondente — se a API adicionar um campo, ele aparece no JSON da CLI também.
* Os `error.code` são estáveis. Mensagens podem mudar entre versões.