Curl Pretty Print JSON: jq, python, CLI formatarc e opções no navegador

TL;DR — o one-liner

Se o jq já estiver instalado, isto é tudo de que você precisa:

curl -s https://api.example.com/users/1 | jq .

Não tem o jq? Use o Python, que já vem na maioria dos sistemas:

curl -s https://api.example.com/users/1 | python3 -m json.tool

Prefere o navegador? Cole a resposta no FormatArc JSON Formatter — sem instalação, funciona offline após o primeiro carregamento. O restante deste guia compara as quatro opções para você escolher a certa em cada situação.

Por que a saída do curl é difícil de ler

Quando você consulta uma API com o curl, a resposta JSON volta em uma única linha.

curl -s https://api.example.com/users/1

{"id":1,"name":"Tanaka","email":"tanaka@example.com","address":{"city":"Tokyo","zip":"100-0001"},"roles":["admin","editor"]}

Sem quebras de linha, sem indentação. À medida que o aninhamento aumenta, fica impossível de ler. A seguir estão quatro formas de transformar essa parede de texto em JSON legível.

Formatar com jq

O jq é o processador de JSON em linha de comando mais popular.

Instalando o jq

# macOS
brew install jq

# Ubuntu / Debian
sudo apt install jq

# Windows (Chocolatey)
choco install jq

Uso básico

Encaminhe a saída do curl para o jq usando um filtro de ponto.

curl -s https://api.example.com/users/1 | jq .

{
  "id": 1,
  "name": "Tanaka",
  "email": "tanaka@example.com",
  "address": {
    "city": "Tokyo",
    "zip": "100-0001"
  },
  "roles": [
    "admin",
    "editor"
  ]
}

A flag -s silencia a barra de progresso do curl para que apenas o JSON chegue ao jq.

Filtros úteis

O jq faz mais do que formatar. Ele consegue extrair campos específicos da resposta.

Extrair uma única chave:

curl -s https://api.example.com/users/1 | jq '.name'

"Tanaka"

Acessar chaves aninhadas com a notação de ponto:

curl -s https://api.example.com/users/1 | jq '.address.city'

"Tokyo"

Pegar um campo de cada elemento de um array:

curl -s https://api.example.com/users | jq '.[].name'

"Tanaka"
"Suzuki"
"Sato"

Filtrar elementos por condição com select:

curl -s https://api.example.com/users | jq '.[] | select(.roles[] == "admin")'

Formatar cabeçalhos da resposta e JSON juntos (`curl -i`)

Os exemplos com -s acima descartam tudo, exceto o corpo da resposta. Quando você depura uma API e quer ver tanto os cabeçalhos quanto o corpo, recorre ao curl -i. O problema: encaminhar curl -i | jq . sempre falha, porque o bloco de cabeçalhos no topo do stream não é JSON.

curl -is https://api.example.com/users/1 | jq .
# parse error: Invalid numeric literal at line 1, column 9

Você precisa manter os cabeçalhos visíveis, mas direcionar apenas o corpo JSON para o jq.

Dividir o stream: cabeçalhos para o stderr, corpo para o stdout

O curl -D <arquivo> grava os cabeçalhos da resposta no arquivo que você indicar. Aponte para /dev/stderr e os cabeçalhos são impressos no terminal, enquanto o stdout mantém apenas o corpo — pronto para o jq.

curl -sSD /dev/stderr https://api.example.com/users/1 | jq .

HTTP/2 200
content-type: application/json
cache-control: no-store
date: Mon, 19 May 2026 09:30:00 GMT

{
  "id": 1,
  "name": "Tanaka",
  ...
}

Os cabeçalhos chegam ao terminal, mas nunca entram no pipe, então o jq enxerga apenas JSON válido. No PowerShell do Windows, /dev/stderr não existe — grave em um arquivo e use cat depois (veja o padrão de divisão em arquivos abaixo).

Dividir em arquivos: salvar cabeçalhos e corpo separadamente

Quando você quer manter ambos para inspecionar depois (por exemplo, salvar uma requisição que falhou para triagem), divida em dois arquivos com -D e -o.

curl -sSD head.txt -o body.json https://api.example.com/users/1
cat head.txt
jq . body.json

Isso funciona de forma idêntica no macOS, Linux e Windows (qualquer shell). Use quando também quiser fazer grep nos cabeçalhos mais tarde, ou anexá-los a um relatório de bug.

Transforme em um alias permanente

Na maioria das vezes você quer um comando curto. Adicione isto ao seu ~/.bashrc ou ~/.zshrc:

alias curl-json='curl -sSD /dev/stderr'
curl-json-format() { curl-json "$@" | jq .; }

Agora curl-json-format https://api.example.com/users/1 imprime os cabeçalhos no terminal e o JSON formatado abaixo. O nome da função é propositalmente explícito para não colidir com nada mais no histórico do seu shell.

Atalho `--json` do curl 7.82+ (lado da requisição)

O outro lado de formatar uma resposta é enviar JSON em uma requisição. Desde o curl 7.82 (março de 2022), o atalho --json define Content-Type: application/json, Accept: application/json e --data em uma única flag.

curl --json '{"name":"alice"}' https://api.example.com/users

Ele não formata a resposta por conta própria — encaminhe para o jq ou um dos métodos abaixo para formatar o corpo. Mas remove as três flags habituais dos exemplos de requisição, então combinar --json na requisição com curl-json-format na resposta dá um padrão limpo em duas etapas para qualquer API REST.

Checklist: a resposta do curl é mesmo JSON válido?

Antes de encaminhar uma resposta para o jq, o json.tool ou qualquer formatador, confirme duas coisas: que o servidor declarou o corpo como JSON e que o próprio corpo está bem formado. O formato de intercâmbio de dados JSON é definido pela RFC 8259 (STD 90), e a gramática está resumida em json.org. Use este checklist:

O Content-Type é application/json. A RFC 8259 registra application/json como o media type do JSON. Inspecione o cabeçalho da resposta com curl -i ou com o padrão curl -sSD /dev/stderr acima e confirme que a linha content-type exibe application/json. Um tipo como text/html geralmente significa que uma página de erro, um redirecionamento de login ou uma resposta de proxy entrou no lugar do JSON.
O corpo é JSON bem formado. Um texto JSON deve ser um único valor: um objeto, um array, uma string, um número ou um dos literais true, false ou null (RFC 8259, seção 2). As chaves de objetos precisam ser strings entre aspas duplas, aspas simples não são permitidas e vírgulas finais são inválidas. A RFC 8259 (seção 8.1) exige que o JSON trocado entre sistemas que não fazem parte de um ecossistema fechado seja codificado em UTF-8.
Ele faz o parse sem erros. O teste prático é um parser aceitar o corpo. Se jq . ou python3 -m json.tool retornar um erro de parse em vez de uma saída formatada, o corpo não é JSON válido, independentemente do cabeçalho Content-Type. Comentários (// ou /* */) não fazem parte do JSON; um corpo que os contenha é JSONC ou JSON5, não JSON.

Formatar com o json.tool do Python

Se o Python já estiver instalado, você não precisa de nenhuma ferramenta extra. A biblioteca padrão inclui o json.tool.

curl -s https://api.example.com/users/1 | python3 -m json.tool

{
    "id": 1,
    "name": "Tanaka",
    "email": "tanaka@example.com",
    "address": {
        "city": "Tokyo",
        "zip": "100-0001"
    },
    "roles": [
        "admin",
        "editor"
    ]
}

Ele não tem os recursos de filtragem do jq, mas para uma formatação rápida resolve. Em sistemas com apenas Python 2, use python no lugar de python3.

Formatar com a CLI formatarc

Instalação e uso

O formatarc roda na hora via npx, sem necessidade de instalação.

curl -s https://api.example.com/users/1 | npx formatarc json-format

{
  "id": 1,
  "name": "Tanaka",
  "email": "tanaka@example.com",
  "address": {
    "city": "Tokyo",
    "zip": "100-0001"
  },
  "roles": [
    "admin",
    "editor"
  ]
}

Para uso frequente, instale globalmente para pular o tempo de inicialização do npx.

npm install -g formatarc
curl -s https://api.example.com/users/1 | formatarc json-format

Encaminhar para YAML ou CSV

O formatarc também consegue converter a saída JSON para YAML ou CSV no mesmo pipeline.

curl -s https://api.example.com/users/1 | npx formatarc json-to-yaml

id: 1
name: Tanaka
email: tanaka@example.com
address:
  city: Tokyo
  zip: "100-0001"
roles:
  - admin
  - editor

Consulte o guia da CLI formatarc para a lista completa de comandos e opções.

Formatar no navegador

Usando o FormatArc JSON Formatter

Se você prefere não usar a linha de comando, copie a saída do curl e cole no JSON Formatter.

Copie a resposta do curl
Abra o FormatArc JSON Formatter
Cole na área de texto à esquerda
Clique em "Format"

O resultado formatado pode ser copiado ou convertido para YAML / CSV diretamente na ferramenta.

Tratando erros de parse

Se o JSON contiver erros de sintaxe, a formatação vai falhar. Causas comuns e correções estão em Como corrigir erros de parse de JSON.

Se a resposta da API contiver comentários // ou /* */ e o jq ou o json.tool não conseguir fazer o parse, o payload pode ser JSONC ou JSON5. Veja Como adicionar comentários ao JSON para as alternativas que funcionam.

Se você quiser que uma URL de JSON seja formatada automaticamente assim que abrir em uma aba, uma extensão do Chrome é uma alternativa ao curl. Veja As melhores extensões de JSON Formatter para Chrome comparadas.

Qual método escolher

Método	Instalação	Filtragem	Indicado para
jq	Necessária	Poderosa	Quem trabalha com APIs todos os dias
Python json.tool	Nenhuma (precisa de Python)	Nenhuma	Formatação rápida sem ferramentas extras
CLI formatarc	npx (na hora)	Nenhuma (apenas conversão)	Quando você também precisa converter para YAML/CSV
Navegador (FormatArc)	Nenhuma	Nenhuma	Quem não usa CLI ou para formatações pontuais

Usar o jq no dia a dia e adicionar a CLI formatarc quando precisar de conversão de formatos é uma combinação eficiente.

Resumo

Este artigo apresentou quatro formas de formatar JSON a partir do curl: jq, o json.tool do Python, a CLI formatarc e ferramentas baseadas no navegador. O jq é a opção mais completa, com seus recursos de filtragem, e o padrão curl -sSD /dev/stderr | jq . mantém os cabeçalhos da resposta visíveis sem quebrar o parse. O json.tool do Python não exige instalação na maioria dos sistemas. A CLI formatarc adiciona conversão para YAML e CSV ao pipeline. Para uma abordagem visual, experimente o FormatArc JSON Formatter.

TL;DR — o one-liner

Por que a saída do curl é difícil de ler

Formatar com jq

Instalando o jq

Uso básico

Filtros úteis

Formatar cabeçalhos da resposta e JSON juntos (curl -i)

Dividir o stream: cabeçalhos para o stderr, corpo para o stdout

Dividir em arquivos: salvar cabeçalhos e corpo separadamente

Transforme em um alias permanente

Atalho --json do curl 7.82+ (lado da requisição)

Checklist: a resposta do curl é mesmo JSON válido?

Formatar com o json.tool do Python

Formatar com a CLI formatarc

Instalação e uso

Encaminhar para YAML ou CSV

Formatar no navegador

Usando o FormatArc JSON Formatter

Tratando erros de parse

Qual método escolher

Artigos relacionados

Resumo

Formatar cabeçalhos da resposta e JSON juntos (`curl -i`)

Atalho `--json` do curl 7.82+ (lado da requisição)