curl es la herramienta universal para hablar con APIs HTTP desde la línea de comandos, pero su sintaxis de flags acumula opciones que pocas personas recuerdan de memoria: cabeceras, autenticación, cuerpo JSON, seguimiento de redirecciones, timeouts. Este generador de comandos curl construye la línea completa a partir de un formulario, evitando errores de comillas y escapado que rompen silenciosamente peticiones a producción.
Cabeceras y tipos de contenido: el error más común
Olvidar -H "Content-Type: application/json" al enviar un cuerpo JSON hace que muchos servidores interpreten la petición como application/x-www-form-urlencoded y devuelvan un 400 o, peor, procesen el JSON como texto plano sin parsear los campos. Usa -H una vez por cada cabecera adicional; para APIs que requieren varias (Authorization, Accept, Content-Type) el orden no importa pero cada una necesita su propio flag.
Autenticación: Bearer, Basic y API keys
Para tokens Bearer (OAuth2, JWT), usa -H "Authorization: Bearer TOKEN". Para autenticación básica, -u usuario:contraseña codifica automáticamente en Base64 sin que tengas que hacerlo a mano. Para APIs que usan una cabecera de key propietaria (X-API-Key, X-Auth-Token), trátala como cualquier otra cabecera con -H. Nunca pases credenciales como parámetro de URL: quedan registradas en logs de acceso, historiales de shell y proxies intermedios.
Cuerpo de la petición: -d, --data-raw y form-data
-d envía datos como formulario por defecto, pero si el contenido empieza por { curl no lo detecta automáticamente como JSON: necesitas la cabecera Content-Type explícita. Para subir archivos, -F "file=@ruta/archivo.pdf" construye una petición multipart/form-data correctamente delimitada, algo tedioso de escribir a mano. Ten cuidado con las comillas en JSON: en sistemas Windows con cmd.exe las comillas dobles necesitan escaparse distinto que en Bash o PowerShell, una fuente constante de errores al copiar comandos entre sistemas operativos.
Seguir redirecciones, timeouts y reintentos
Por defecto curl no sigue redirecciones HTTP 301/302; si tu API o sitio redirige, necesitas -L. Para evitar que un script se quede colgado indefinidamente esperando una respuesta, usa --max-time 30 (timeout total) o --connect-timeout 5 (solo para establecer la conexión). En scripts de automatización que dependen de servicios externos poco fiables, --retry 3 --retry-delay 2 reintenta automáticamente ante fallos de red transitorios sin que tengas que envolver curl en un bucle manual.
Depurar peticiones: -v, -i y volcado de cabeceras
-v (verbose) muestra toda la conversación TCP/TLS: el handshake, las cabeceras enviadas y recibidas, y el cuerpo de la respuesta, siendo la forma más rápida de diagnosticar por qué una API rechaza tu petición. -i incluye solo las cabeceras de respuesta en la salida estándar, útil para revisar códigos de estado y cabeceras de caché sin el ruido del handshake TLS. Combina -w "%{http_code}\n" para extraer solo el código de estado en scripts que necesitan tomar decisiones automatizadas.
curl dentro de scripts y pipelines de CI/CD
En un pipeline de despliegue, curl suele usarse para healthchecks post-despliegue o para notificar a un webhook (Slack, Discord, Teams). Usa siempre --fail para que curl devuelva un código de salida distinto de cero ante respuestas 4xx/5xx; sin este flag, curl considera exitosa cualquier petición que reciba respuesta HTTP, aunque sea un 500, y tu script de CI seguirá adelante creyendo que todo fue bien.
Alternativas y cuándo usar cada una
curl es ideal para scripts y automatización por su ubicuidad (viene preinstalado en casi cualquier sistema Linux). Para exploración interactiva de APIs con historial y colecciones, herramientas como Postman o Insomnia son más cómodas, pero generan una dependencia visual que no sirve para un script reproducible. Si necesitas ejecutar la misma petición repetidamente con datos variables, un pequeño script de Bash que envuelva el comando curl generado aquí es la solución más portable.
Casos de uso comunes
- Probar endpoints de una API REST antes de integrarlos en código de producción.
- Automatizar healthchecks HTTP dentro de un pipeline de CI/CD.
- Enviar notificaciones a webhooks de Slack o Discord desde scripts de despliegue.
- Depurar por qué una API devuelve un código de error concreto.
- Subir archivos a un endpoint multipart/form-data sin herramientas gráficas.
Buenas prácticas
- Añade siempre --fail en scripts para detectar respuestas 4xx/5xx.
- Nunca pases tokens o contraseñas como parámetro de URL.
- Usa --max-time en cualquier petición dentro de un script automatizado.
- Especifica Content-Type explícitamente al enviar JSON.
- Usa -v solo para depurar; no lo dejes en scripts que corren en producción por el ruido en logs.