Saber leer un curl pegado acelera el trabajo con APIs

Un comando curl copiado de la documentación o de las herramientas de desarrollo del navegador suele tener este aspecto:

curl -X POST 'https://api.example.com/v1/items?limit=10' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","tags":["a","b"]}'

Es sencillo una vez que se sabe leer, pero hay combinaciones de opciones que cambian el comportamiento, y desconocerlas lleva al clásico «el mismo comando no funciona aquí».

Lista de opciones de curl (por finalidad)

Las opciones que más te encontrarás, agrupadas por lo que hacen. Para ver todo lo que admite tu versión, ejecuta curl --help all (lista completa), curl --help category (lista de categorías) o man curl (detalles).

Construir la petición

Opción Significado
-X, --request Establece el método HTTP (GET / POST / PUT / DELETE)
-H, --header Añade una cabecera de petición; se puede repetir
-A, --user-agent Establece la cabecera User-Agent
-e, --referer Establece la cabecera Referer
-b, --cookie Envía cookies
-c, --cookie-jar Guarda en un archivo las cookies recibidas
-u, --user Autenticación básica (user:password)
-G, --get Pone los datos de -d en la cadena de consulta de la URL en lugar de en el cuerpo

Enviar datos

Opción Significado
-d, --data Envía un cuerpo de petición. Implica POST
--data-raw Igual que -d, pero no trata una @ inicial como nombre de archivo
--data-binary Envía los datos exactamente como se dan, conservando los saltos de línea (archivos, binario)
--data-urlencode Aplica codificación porcentual al valor antes de enviarlo
-F, --form Envía como multipart/form-data (subida de archivos)
-T, --upload-file Sube un archivo (un PUT sobre HTTP)
--json Envía JSON y establece también Content-Type y Accept (curl 7.82+)

Gestionar la respuesta

Opción Significado
-o, --output Escribe la respuesta en un archivo
-O, --remote-name Guarda con el nombre de archivo de la URL
-i, --include Incluye las cabeceras de la respuesta en la salida
-I, --head Envía HEAD y muestra solo las cabeceras
-D, --dump-header Escribe las cabeceras de la respuesta en un archivo
-w, --write-out Al terminar, imprime detalles como %{http_code}
-r, --range Solicita un intervalo de bytes (por ejemplo 0-99)
-C - Reanuda un archivo descargado parcialmente
--compressed Solicita una transferencia comprimida (gzip, etc.)

Salida y errores

Opción Significado
-s, --silent Oculta el indicador de progreso
-S, --show-error Con -s, sigue mostrando los errores
-v, --verbose Muestra el intercambio completo, incluidas las cabeceras de la petición
-f, --fail Con HTTP 400 o superior, no imprime el cuerpo y sale con el código 22
-#, --progress-bar Muestra el progreso como una barra

Conexión, tiempos de espera y redirecciones

Opción Significado
-L, --location Sigue las redirecciones (3xx)
--max-redirs Número máximo de redirecciones que seguir
--connect-timeout Segundos de espera para la conexión
-m, --max-time Máximo de segundos en total; la transferencia se aborta pasado ese tiempo
--retry Número de reintentos ante errores transitorios
-x, --proxy Conecta a través de un proxy
--resolve Resuelve un nombre de host a una IP dada (host:port:address), útil para probar un servidor nuevo sin cambiar el DNS
-4, -6 Usa solo IPv4 / IPv6
-g, --globoff No expande [] ni {} en la URL

TLS (HTTPS)

Opción Significado
-k, --insecure Omite la verificación del certificado del servidor
--cacert Archivo de certificado de CA con el que verificar
-E, --cert / --key Certificado de cliente y clave privada

-X POST suele sobrar

Añadir -d ya convierte la petición en POST. Estas dos son idénticas:

curl -X POST https://api.example.com/items -d '{"a":1}'
curl https://api.example.com/items -d '{"a":1}'

El problema es el caso contrario. -X GET junto con -d produce un GET con cuerpo, algo que proxies y servidores pueden ignorar o rechazar: una causa clásica de «funciona en local y falla en producción».

Repetir -d une los valores con &. Útil para formularios, fatal para JSON:

# No es lo que quiere: envía {"a":1}&{"b":2}
curl -d '{"a":1}' -d '{"b":2}' https://api.example.com/items

Una @ inicial en -d lee un archivo

Cuando el valor pasado a -d empieza por @, curl lee ese archivo y envía su contenido:

curl -d @payload.json https://api.example.com/items   # envía el contenido del archivo

Práctico, hasta que pasa un nombre de usuario tal cual:

# Intención: enviar la cadena "@alice"
# Realidad: curl busca el archivo ./alice y falla si no existe
curl -d '@alice' https://api.example.com/items

Para enviar un valor que contenga @ literalmente, use --data-raw, que no le da ningún significado especial.

El Content-Type no pasa a JSON por sí solo

Con -d, curl envía Content-Type: application/x-www-form-urlencoded salvo que indique otra cosa. Si manda JSON sin la cabecera, el servidor no podrá analizarlo:

curl -H 'Content-Type: application/json' \
     -d '{"name":"Alice"}' https://api.example.com/items

Desde curl 7.82 existe --json, que establece a la vez Content-Type: application/json y Accept: application/json. En entornos antiguos no está disponible, así que escriba la cabecera explícitamente en los comandos que vaya a compartir.

Las comillas causan más fallos que ninguna otra cosa

Estilo Comportamiento
'...' (simples) Pasa $ y " sin tocarlos. Úselas para JSON
"..." (dobles) La shell expande $variables

El JSON contiene comillas dobles, así que las exteriores deben ser simples:

# Correcto
curl -d '{"name":"Alice"}' https://api.example.com/items

# La shell elimina las comillas interiores y el cuerpo se rompe
curl -d "{"name":"Alice"}" https://api.example.com/items

Cuando necesite un token desde una variable de entorno, combine ambas deliberadamente:

curl -H "Authorization: Bearer $TOKEN" \
     -d '{"name":"Alice"}' https://api.example.com/items

El símbolo del sistema de Windows no interpreta las comillas simples, y en PowerShell curl puede ser un alias de Invoke-WebRequest. Llame a curl.exe explícitamente o ejecute el comando en WSL o Git Bash.

Qué opción de datos usar

La familia -d se diferencia en qué se transforma antes de enviar.

Opción Transformación Ideal para
-d Un valor que empieza por @ lee un archivo; se eliminan los saltos de línea del archivo Formularios, JSON corto
--data-raw @ no es especial Enviar tal cual una cadena que contiene @
--data-binary Se envía exactamente como se da, con los saltos de línea Archivos en los que importan los saltos de línea, datos binarios
--data-urlencode Aplica codificación porcentual al valor Texto no ASCII o símbolos en valores de formularios y consultas
-F Se envía como multipart/form-data Subida de archivos

Usa -d @payload.json para leer un archivo y -d @- para leer la entrada estándar. Para un archivo JSON cuyos saltos de línea quieras conservar, o para datos binarios, usa --data-binary @file.

Tiempos de espera y reintentos

Cuando curl se ejecuta desde un script, fija límites de tiempo para que nunca espere eternamente:

curl --connect-timeout 5 --max-time 30 --retry 3 https://api.example.com/items
  • --connect-timeout: segundos de espera para la conexión
  • -m, --max-time: segundos para toda la transferencia. Concede más tiempo en las descargas grandes
  • --retry: cuántas veces reintentar ante un tiempo de espera agotado o ciertos errores HTTP (429, 502, 503, 504 y similares)

Por defecto, curl sale con 0 incluso cuando el servidor devuelve 404 o 500. Para detectar el fallo en un script, añade -f:

curl -fsS https://api.example.com/health || echo "failed"

Para obtener solo el código de estado, usa -w:

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/

En Windows, escribe NUL en lugar de /dev/null. -w admite además variables como %{time_total} (segundos totales).

Códigos de salida habituales

Una guía para comprobar $? en scripts (la lista completa está en “EXIT CODES” de man curl).

Código Significado
0 Éxito
6 No se pudo resolver el host
7 Falló la conexión
22 HTTP 400 o superior (con -f)
28 Tiempo de espera agotado
35 Falló el handshake TLS
60 No se pudo verificar el certificado del servidor

Usar curl.exe en Windows

Windows 10 (versión 1803) y posteriores incluyen curl.exe. Las opciones son las mismas que en Linux y macOS, pero la forma de escribir el comando depende del shell.

Elemento Símbolo del sistema (cmd) PowerShell
Cómo llamarlo curl / curl.exe Escribe curl.exe (curl puede ser un alias de Invoke-WebRequest)
Comillas Solo comillas dobles (las simples no funcionan) Simples o dobles, pero las " interiores pueden perderse
Continuación de línea ^ Acento grave `

En cmd, escapa las comillas dobles dentro del JSON con \":

curl.exe -X POST -H "Content-Type: application/json" -d "{\"name\":\"Alice\"}" https://api.example.com/items

PowerShell también deforma con facilidad las comillas del JSON, así que lo más fiable es poner el JSON en un archivo y pasarlo con -d @body.json:

curl.exe -X POST -H "Content-Type: application/json" -d "@body.json" https://api.example.com/items

Si dudas, ejecuta el comando desde WSL o Git Bash, donde funcionan las comillas simples y se pueden usar tal cual los ejemplos de este artículo.

Entrecomille las URL que contengan &

Si pega una URL con varios parámetros sin comillas, la shell interpreta & como «ejecutar en segundo plano» y trunca el comando:

# Roto: solo se envía limit=10
curl https://api.example.com/items?limit=10&offset=20

# Correcto
curl 'https://api.example.com/items?limit=10&offset=20'

Los valores con espacios o caracteres no ASCII necesitan codificación porcentual. Puede comprobarla con el codificador/decodificador de URL, o dejar que curl construya la cadena de consulta con -G y --data-urlencode:

curl -G https://api.example.com/search --data-urlencode 'q=hola mundo'

Dos opciones ante las que conviene dudar

-k / --insecure desactiva la verificación del certificado. Tiene sentido al probar un certificado autofirmado en local, pero el incidente clásico es añadirla para silenciar un error y dejarla en un comando compartido o en producción. Los problemas de certificado se arreglan en el certificado.

-L / --location sigue las redirecciones. Es cómodo, pero el tratamiento del método y del cuerpo en un POST redirigido puede cambiar; fíjelo con --post301, --post302 o --post303 cuando importe.

Convertir el comando en código

Una vez leído el comando, transcribir cabeceras y cuerpos a mano es propenso a errores. Péguelo en el conversor de cURL y obtendrá código de petición para JavaScript, Python, Go y otros lenguajes, con el entrecomillado y la separación de cabeceras ya resueltos.

Para formatear o validar el JSON que envía, use el formateador JSON; para inspeccionar una cadena de consulta, parámetros de URL a JSON. Todo se ejecuta en su navegador, así que un comando con un token de autenticación nunca se transmite.

Resumen

  • -d ya implica POST; -X GET con -d produce un incómodo GET con cuerpo
  • Un valor de -d que empieza por @ lee un archivo: use --data-raw para enviarlo como texto
  • -d por sí solo significa codificación de formulario. Para JSON, ponga la cabecera o use --json (curl 7.82+)
  • Comillas simples alrededor del JSON; dobles solo donde necesite expandir variables
  • Entrecomille las URL con &; construya consultas codificadas con -G --data-urlencode
  • -k no sirve para silenciar errores, y -L puede cambiar el comportamiento de un POST

Preguntas frecuentes

¿Cómo listo todas las opciones de curl?

Ejecuta curl --help all para ver todas las opciones, o curl --help category para las categorías. man curl tiene las descripciones completas. En Windows, usa curl.exe --help all. Las tablas de “Lista de opciones de curl (por finalidad)” de arriba recogen las que más usarás.

¿Qué diferencia hay entre curl y curl.exe?

En Windows PowerShell, curl puede ser un alias de Invoke-WebRequest, que tiene otras opciones. Escribe curl.exe para llamar al curl de verdad. En el Símbolo del sistema, cualquiera de los dos nombres ejecuta curl.exe.

curl sale con 0 incluso con un 404. ¿Puedo hacer que falle?

Añade -f (--fail): con HTTP 400 o superior, curl no imprime el cuerpo y sale con el código 22. Es útil para detectar fallos en scripts. Combínalo con --connect-timeout y --max-time para que no pueda quedarse colgado.

¿Hace falta escribir -X POST?

Normalmente no: añadir -d o -F convierte la petición en POST automáticamente. Escribirlo documenta la intención, lo cual tiene valor en un comando compartido. Lo que conviene evitar es -X GET junto con -d, que produce un GET con cuerpo y algunos servidores y proxies lo ignoran o lo rechazan.

¿Qué diferencia hay entre -d y --data-raw?

Solo el tratamiento de la @ inicial. Con -d, un valor que empieza por @ se toma como nombre de archivo y se envía su contenido; --data-raw envía la cadena tal cual. Use --data-raw para datos que contengan @ de forma legítima, como una dirección de correo.

He enviado JSON pero el servidor no lo interpreta

Con -d, el Content-Type por defecto es application/x-www-form-urlencoded, así que necesita -H 'Content-Type: application/json'. Desde curl 7.82, --json establece la cabecera por usted.

El comando no funciona en Windows

El símbolo del sistema no interpreta las comillas simples y PowerShell puede tener curl como alias de Invoke-WebRequest. Llame a curl.exe explícitamente o ejecute el comando desde una shell que maneje comillas simples, como WSL o Git Bash.

¿Es seguro pegar un comando que contiene un token?

El conversor de cURL funciona íntegramente en su navegador y nada de lo que pega se transmite. Eso sí, el código convertido sigue conteniendo el token, así que muévalo a una variable de entorno antes de subir el código.