Curl con JSON formateado: jq, python, CLI de formatarc y opciones en el navegador

En resumen: el comando de una sola línea

Si ya tienes jq instalado, esto es todo lo que necesitas:

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

¿No tienes jq? Usa Python, que viene incluido en la mayoría de los sistemas:

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

¿Prefieres un navegador? Pega la respuesta en el formateador de JSON de FormatArc: sin instalación y funciona sin conexión después de la primera carga. El resto de esta guía compara las cuatro opciones para que elijas la adecuada en cada situación.

Por qué la salida de curl es difícil de leer

Cuando consultas una API con curl, la respuesta JSON llega como una sola línea.

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"]}

Sin saltos de línea ni sangría. A medida que aumenta el anidamiento, esto se vuelve imposible de revisar de un vistazo. Aquí tienes cuatro maneras de convertir ese bloque de texto en JSON legible.

Formatear con jq

jq es el procesador de JSON por línea de comandos más popular.

Instalar jq

# macOS
brew install jq

# Ubuntu / Debian
sudo apt install jq

# Windows (Chocolatey)
choco install jq

Uso básico

Canaliza la salida de curl hacia jq con un filtro de punto.

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"
  ]
}

La opción -s silencia la barra de progreso de curl para que solo el JSON llegue a jq.

Filtros útiles

jq hace más que formatear. Puede extraer campos específicos de la respuesta.

Extraer una sola clave:

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

"Tanaka"

Acceder a claves anidadas con la notación de punto:

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

"Tokyo"

Obtener un campo de cada elemento de un array:

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

"Tanaka"
"Suzuki"
"Sato"

Filtrar elementos por condición con select:

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

Formatear las cabeceras de respuesta y el JSON a la vez (curl -i)

Los ejemplos con -s anteriores descartan todo excepto el cuerpo de la respuesta. Cuando depuras una API y quieres ver tanto las cabeceras como el cuerpo, recurres a curl -i. El problema: canalizar curl -i | jq . siempre falla, porque el bloque de cabeceras al inicio del flujo no es JSON.

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

Necesitas mantener visibles las cabeceras pero enviar solo el cuerpo JSON a jq.

Dividir el flujo: cabeceras a stderr, cuerpo a stdout

curl -D <archivo> escribe las cabeceras de respuesta en el archivo que le indiques. Apúntalo a /dev/stderr y las cabeceras se imprimen en la terminal mientras que stdout conserva solo el cuerpo, listo para 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",
  ...
}

Las cabeceras llegan a la terminal pero nunca entran en la tubería, así que jq solo ve JSON válido. En PowerShell de Windows, /dev/stderr no existe: escribe en un archivo y luego haz cat (consulta el patrón de división en archivos más abajo).

Dividir en archivos: guardar cabeceras y cuerpo por separado

Cuando quieres conservar ambos para inspeccionarlos después (por ejemplo, guardar una petición fallida para analizarla), divídelos en dos archivos con -D y -o.

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

Esto funciona de forma idéntica en macOS, Linux y Windows (cualquier shell). Úsalo cuando además quieras hacer grep sobre las cabeceras más tarde, o adjuntarlas a un informe de errores.

Convertirlo en un alias permanente

La mayoría de las veces quieres un único comando corto. Añade esto a tu ~/.bashrc o ~/.zshrc:

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

Ahora curl-json-format https://api.example.com/users/1 imprime las cabeceras en la terminal y, debajo, el JSON formateado. El nombre de la función es deliberadamente explícito para que no choque con nada más en el historial de tu shell.

Atajo --json de curl 7.82+ (lado de la petición)

La otra cara de formatear una respuesta es enviar JSON en una petición. Desde curl 7.82 (marzo de 2022), el atajo --json establece Content-Type: application/json, Accept: application/json y --data en una sola opción.

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

Por sí solo no formatea la respuesta: canalízala hacia jq o hacia alguno de los métodos siguientes para dar formato al cuerpo. Pero elimina las tres opciones habituales de los ejemplos de petición, así que combinar --json para la petición con curl-json-format para la respuesta da un patrón limpio de dos pasos para cualquier API REST.

Lista de comprobación: ¿la respuesta de curl es realmente JSON válido?

Antes de canalizar una respuesta hacia jq, json.tool o cualquier formateador, confirma dos cosas: que el servidor declaró el cuerpo como JSON y que el cuerpo en sí está bien formado. El formato de intercambio de datos JSON está definido por RFC 8259 (STD 90), y la gramática se resume en json.org. Usa esta lista de comprobación:

• El Content-Type es application/json. RFC 8259 registra application/json como el tipo de medio del JSON. Inspecciona la cabecera de la respuesta con curl -i o con el patrón curl -sSD /dev/stderr de arriba y confirma que la línea content-type indique application/json. Un tipo como text/html suele significar que se ha colado una página de error, una redirección de inicio de sesión o una respuesta de proxy en lugar de JSON.
• El cuerpo es JSON bien formado. Un texto JSON debe ser un único valor: un objeto, un array, una cadena, un número o uno de los literales true, false o null (RFC 8259, sección 2). Las claves de los objetos deben ser cadenas entre comillas dobles, no se permiten las comillas simples y las comas finales no son válidas. RFC 8259 (sección 8.1) exige que el JSON intercambiado entre sistemas que no forman parte de un ecosistema cerrado se codifique en UTF-8.
• Se analiza sin errores. La prueba práctica es que un analizador acepte el cuerpo. Si jq . o python3 -m json.tool devuelve un error de análisis en lugar de una salida formateada, el cuerpo no es JSON válido, independientemente de la cabecera Content-Type. Los comentarios (// o /* */) no forman parte de JSON; un cuerpo que los contenga es JSONC o JSON5, no JSON.

Formatear con json.tool de Python

Si Python ya está instalado, no necesitas herramientas adicionales. La biblioteca estándar incluye 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"
    ]
}

No tiene las capacidades de filtrado de jq, pero para un formateo rápido cumple su función. En sistemas que solo tienen Python 2, usa python en lugar de python3.

Formatear con la CLI de formatarc

Instalación y uso

formatarc se ejecuta al instante con npx, sin necesidad de instalación.

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 un uso frecuente, instálalo de forma global para evitar el tiempo de arranque de npx.

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

Canalizar hacia YAML o CSV

formatarc también puede convertir la salida JSON a YAML o CSV en la misma tubería.

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

Consulta la guía de la CLI de formatarc para ver la lista completa de comandos y opciones.

Formatear en el navegador

Usar el formateador de JSON de FormatArc

Si prefieres no usar la línea de comandos, copia la salida de curl y pégala en el formateador de JSON.

1. Copia la respuesta de curl
2. Abre el formateador de JSON de FormatArc
3. Pégala en el área de texto de la izquierda
4. Haz clic en "Format"

El resultado formateado se puede copiar o convertir a YAML / CSV directamente desde la herramienta.

Manejo de errores de análisis

Si el JSON contiene errores de sintaxis, el formateo fallará. Las causas y soluciones más comunes se tratan en Cómo solucionar errores de análisis de JSON.

Si la respuesta de la API contiene comentarios // o /* */ y jq o json.tool no logran analizarla, es posible que la carga útil sea JSONC o JSON5. Consulta Cómo añadir comentarios a JSON para conocer las alternativas que sí funcionan.

Si quieres que una URL JSON se formatee automáticamente en cuanto la abras en una pestaña, una extensión de Chrome es una alternativa a curl. Consulta Comparativa de las mejores extensiones de Chrome para formatear JSON.

Qué método elegir

Usar jq para el trabajo diario y añadir la CLI de formatarc cuando necesitas conversión de formatos es una combinación eficiente.

Artículos relacionados

• Consejos para formatear JSON
• Guía de la CLI de formatarc
• Cómo solucionar errores de análisis de JSON
• Guía de sintaxis de JSON
• Cómo añadir comentarios a JSON
• Comparativa de las mejores extensiones de Chrome para formatear JSON

Conclusión

Este artículo cubrió cuatro maneras de formatear el JSON de curl: jq, json.tool de Python, la CLI de formatarc y herramientas basadas en el navegador. jq es la opción más capaz gracias a sus funciones de filtrado, y el patrón curl -sSD /dev/stderr | jq . mantiene visibles las cabeceras de respuesta sin romper el análisis. json.tool de Python no requiere instalación en la mayoría de los sistemas. La CLI de formatarc añade conversión a YAML y CSV en la tubería. Para un enfoque visual, prueba el formateador de JSON de FormatArc.