¿Qué es el comando curl? Ejemplos, flags y peticiones HTTP

¿Qué es el comando curl?

curl es una herramienta de línea de comandos que transfiere datos hacia o desde un servidor a partir de una URL. Se usa sobre todo para enviar peticiones HTTP desde la terminal: llamar a una API, revisar cabeceras y códigos de estado o subir un archivo. Un comando corto muestra qué envió el cliente y qué respondió el servidor.

Nació en 1996 como una pequeña herramienta llamada HttpGet, se rebautizó curl en 1998 y la mantiene Daniel Stenberg. Además de HTTP y HTTPS, habla FTP, SFTP, SMTP, IMAP y muchos otros protocolos. La lista completa de opciones está en el manual de curl.

Sintaxis básica de curl

El comando más sencillo envía una petición GET e imprime el cuerpo de la respuesta:

curl https://api.example.com/users/42

Añade -i para ver también la línea de estado y las cabeceras de respuesta:

curl -i https://api.example.com/users/42

Si le das datos a curl con -d, envía un POST por defecto, así que -X POST es opcional. Los datos salen como application/x-www-form-urlencoded, por lo que para JSON debes poner tú la cabecera:

curl -X POST https://api.example.com/users -H "Content-Type: application/json" -d '{"name": "Alice", "email": "alice@example.com"}'

Desde curl 7.82.0, la opción --json lo hace en un solo paso: envía los datos como POST con las cabeceras JSON Content-Type y Accept, sin comprobar que el JSON sea válido.

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

Flags de curl más usados

Recetas habituales de curl

Probar un endpoint de una API

Llama a un endpoint de API y lee la línea de estado y las cabeceras:

curl -i https://api.example.com/health

Enviar un token

Pasa un token Bearer en la cabecera Authorization. Usa comillas dobles para que la shell expanda $TOKEN:

curl -H "Authorization: Bearer $TOKEN" https://api.example.com/orders/42

Subir un archivo

-F envía una petición multipart/form-data:

curl -F "avatar=@photo.jpg" -F "username=alice" https://api.example.com/upload

Imprimir solo el código de estado

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

Medir el tiempo de respuesta

Las variables de write-out te dan tiempos de una petición, incluido el tiempo hasta el primer byte:

curl -s -o /dev/null -w "ttfb %{time_starttransfer}s total %{time_total}s\n" https://example.com

Errores habituales con curl

• Olvidar el Content-Type de JSON. Con un simple -d el cuerpo sale como datos de formulario y muchas APIs responden 400 o 415. Añade la cabecera o usa --json. Nuestro artículo sobre cómo se envían los parámetros en una petición HTTP POST (en inglés) explica los tres formatos de cuerpo.
• Añadir -X POST a cada -d. Es redundante, y -X mantiene el método incluso tras una redirección, lo que puede ocultar el comportamiento real.
• Las comillas. En bash, las comillas simples alrededor del JSON protegen las dobles de dentro, pero también impiden que se expanda $TOKEN. El cmd de Windows necesita comillas dobles con escape.
• Secretos en el historial. Un token escrito tras -H acaba en el historial de tu shell. Léelo de una variable de entorno o de un archivo.
• Fiarse del código de salida. Por defecto, curl considera correcta la transferencia de un 404 o un 500. En scripts añade --fail, y usa --fail-with-body si también quieres el cuerpo.
• Dejar -k en un script. Desactiva la comprobación del certificado, así que un ataque de intermediario pasa inadvertido.
• Olvidar -L. Sin él, curl se detiene en el primer 301 o 302.

curl en pruebas de API, CI y monitorización

Como curl está en casi todas las máquinas, es la forma más rápida de reproducir una llamada que falla y la pieza habitual de las pruebas de API en un pipeline. Una prueba de humo tras un despliegue puede ser una sola línea, con tiempo límite y --fail para que un estado malo haga fallar la compilación:

curl --fail --max-time 10 -s -o /dev/null https://example.com/health

• ¿Sin terminal a mano? La herramienta gratuita curl Online funciona como curl en el navegador: envía peticiones GET, POST, PUT, PATCH, DELETE, HEAD u OPTIONS y lee el estado, las cabeceras, el cuerpo, el certificado y el desglose de tiempos. Los métodos seguros se ejecutan desde seis regiones de AWS para que puedas compararlas.
• Convertir un comando en una prueba. El conversor de cURL a k6 convierte un comando curl en un script k6, y el artículo sobre importar cURL, HAR, Postman u OpenAPI a pruebas de carga (en inglés) cubre los demás formatos.
• Seguir comprobando tras el despliegue. Un curl en cron es fácil de escribir y fácil de olvidar. La monitorización de APIs lanza la petición con un calendario desde varias ubicaciones, comprueba estado, cuerpo, cabeceras y tiempo de respuesta, y te avisa. El plan gratuito comprueba cada 5 minutos en la monitorización de APIs de LoadFocus.
• No es una herramienta de pruebas de carga. --parallel (desde curl 7.66.0) ejecuta transferencias a la vez, hasta 50 de forma predeterminada. Informa de cada transferencia, no de percentiles, rampa de usuarios ni resultados por región, y sale de una sola máquina. Para tráfico real usa pruebas de carga desde regiones cloud.

Preguntas frecuentes: comando curl

¿Cuál es la diferencia entre -d y --data-raw?

Con -d, un valor que empieza por @ se lee como nombre de archivo. Con --data-raw, ese mismo valor se envía tal cual. Usa --data-raw cuando tus datos empiecen de verdad por un carácter @.

¿Cómo envío un método HTTP personalizado?

Con -X, por ejemplo curl -X PUT o curl -X DELETE. Normalmente no necesitas -X para GET, HEAD o POST, porque curl elige el método a partir de las demás opciones.

¿Cómo veo exactamente lo que envía curl?

Añade -v para obtener salida detallada. Muestra las cabeceras de petición enviadas, las de respuesta recibidas y detalles de la conexión TLS.

¿Cómo mantengo las cookies entre varias llamadas de curl?

Guárdalas con -c cookies.txt (cookie jar) en la primera llamada y envíalas con -b cookies.txt en las siguientes.

¿Puede curl ejecutar peticiones en paralelo?

Sí. Desde 7.66.0, la opción --parallel (-Z) ejecuta varias transferencias a la vez, 50 por defecto, y --parallel-max lo cambia. Es útil para descargas, pero no sustituye a una prueba de carga.

¿Puedo usar curl como herramienta de pruebas de carga?

Para un puñado de peticiones concurrentes, sí. No agrega los resultados en percentiles, no sube usuarios de forma progresiva ni se ejecuta desde varias regiones. Para eso, convierte la llamada en una prueba de k6 o JMeter y ejecútala en la nube.