Herramientas mencionadas en este artículo
Abre la herramienta en el navegador mientras lees y prueba el flujo al instante.
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
-dya implica POST;-X GETcon-dproduce un incómodo GET con cuerpo- Un valor de
-dque empieza por@lee un archivo: use--data-rawpara enviarlo como texto -dpor 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 -kno sirve para silenciar errores, y-Lpuede 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.
