curl: la navaja suiza de HTTP desde la terminal — guía práctica

Si has pasado más de cinco minutos en una terminal, casi seguro que ya has usado curl alguna vez, aunque fuera sin saberlo. Está en prácticamente todos los sistemas Linux y macOS, Windows lo incluye de serie desde hace años, y media internet —scripts de despliegue, contenedores, herramientas de monitorización, asistentes de IA— funciona encima de la librería que lo sustenta, libcurl.

Yo lo uso a diario: para comprobar si un enlace de un artículo responde, para descargar imágenes, para hablar con APIs internas y para diagnosticar el servidor sin abrir el navegador. Este guía es un paseo práctico por sus funciones esenciales, con ejemplos que puedes copiar y probar en tu máquina en cinco minutos. No hace falta memorizar nada: basta con saber qué herramientas tiene curl y dónde buscarlas cuando las necesites.

Qué es curl y por qué deberías dominarlo

curl es un programa de línea de comandos que transfiere datos con URLs. Su nombre viene de "see URL" y funciona sobre libcurl, una librería que implementa la friolera de protocolos (HTTP, HTTPS, FTP, SFTP, SMTP, IMAP y una docena más) y que está dentro de prácticamente cualquier software que toca la red en un servidor.

Lo que lo hace indispensable: no necesitas instalar nada, no consume memoria de navegador y puedes automatizarlo. Una petición que haces con el ratón en el navegador la puedes convertir en una línea que se ejecuta todos los días a las 8 de la mañana.

La sintaxis general es siempre la misma:

curl [opciones] [URL]

Todo lo demás son variaciones de esa frase: cómo tratar la respuesta, qué método HTTP usar, qué cabeceras enviar y cómo guardar los resultados.

Hacer una petición con curl: el GET más básico

La primera petición se escribe solo con la URL:

curl https://example.com

Por defecto, curl imprime el cuerpo de la página en la terminal. Esto ya es útil, pero la gracia está en las opciones. Si no quieres el HTML pegado tal cual en la pantalla, descarga el contenido a un archivo con -o o usa el nombre original del archivo con -O:

curl -o /tmp/portada.html https://example.com
curl -O https://example.com/archivo.zip   # guarda como archivo.zip

Y si el servidor redirige (por ejemplo, HTTP a HTTPS o un dominio con www), no olvides -L, que sigue todas las redirecciones hasta el destino final:

curl -L -O https://ejemplo.com/descarga    

Inspeccionar cabeceras con -I

Muchas veces no te importa el contenido, sino lo que dice el servidor en sus cabeceras HTTP: código de estado, tipo de contenido, cabeceras de caché. Con -I haces una petición HEAD, que devuelve cabeceras sin copiar todo el cuerpo:

curl -I https://icenico.es

La respuesta es algo así:

HTTP/2 200
content-type: text/html
cache-control: no-cache, must-revalidate
server: cloudflare

Si ves HTTP/2 200, todo ha ido bien. Es una de las formas más rápidas de comprobar si un sitio está vivo.

Leer APIs y JSON: las opciones de datos

Las APIs REST modernas casi todas hablan en JSON; curl es la herramienta perfecta para hablarle desde la terminal antes de escribir una línea de código.

Para una petición GET pública, solo con la URL:

curl https://api.github.com/repos/curl/curl

Para enviar datos al servidor (crear un recurso, enviar un formulario), se usa -d con los datos y se especifica el método con -X:

curl -X POST https://ejemplo.com/api/usuarios \
  -H "Content-Type: application/json" \
  -d '{"nombre": "Nico", "plan": "premium"}'

En este caso -H añade cabeceras personalizadas — para el content type y, en aplicaciones reales, para el token de autenticación.

Autenticación con tokens

Casi todas las APIs se protegen con un token. Se envía en la cabecera Authorization:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-tu-token-aqui"

Consejo: nunca pegues tokens directamente en la línea de comandos. Usa una variable de entorno:

curl -H "Authorization: Bearer $MI_TOKEN" https://api.ejemplo.com/v1/datos

La API pública de GitHub devuelve JSON directamente desde la terminal. Y cuando la respuesta es larga, curl se combina perfectamente con jq, que ya analizamos en un tutorial de este blog:

curl -s https://api.github.com/repos/curl/curl | jq '.stargazers_count'

-s silencia la barra de progreso, para que en la salida solo aparezca el resultado de jq.

Diagnóstico real: comprobar el estado de un servidor con -w

Probablemente el uso más útil para el día a día de un sitio web: comprobar que un endpoint devuelve 200 sin abrir el navegador. La opción -w permite escribir un mensaje personalizado con variables del tipo %{http_code} (código de estado) o %{time_total} (tiempo total de la petición):

$ curl -s -o /dev/null -w "HTTP %{http_code} · %{time_total}s\n" https://icenico.es

HTTP 200 · 0.41s
✓ Diagnóstico completado: el sitio responde

Desglose de la línea:

• -s: modo silencioso, no imprime la barra.
• -o /dev/null: descarta el cuerpo de la respuesta (no queremos el HTML).
• -w "...": formatea el mensaje final con variables de curl.

Este comando es la base de cualquier health check en un script de cron o de monitorización. Para comprobar un enlace o saber si una URL del sector devuelve 404 o 403 (muy frecuente en la web actual), basta cambiar la URL y mirar el código que sale.

También puedes verificar la cabecera Cache-Control de tu propio sitio para confirmar que el cache está bien configurado en producción:

curl -sI https://icenico.es/content/posts.json | grep -i cache-control

Descargar archivos y controlar el ritmo

Además de APIs, curl es un gestor de descargas potente:

curl -L -o /tmp/instalador.run https://ejemplo.com/descargas/instalador.run

Opciones útiles para transferencias grandes:

• -C -: reanuda una descarga interrumpida.
• --limit-rate 500k: limita la velocidad a 500 kB/s y a no saturar la conexión.
• -o archivo: elegir el nombre de destino.
• -O: conservar el nombre original del archivo.

Para un archivo que cambia cada poco y quieres siempre la última versión:

curl -L -O https://ejemplo.com/productos/latest.json

Seguridad y buenas prácticas

curl es seguro por defecto, pero hay hábitos que conviene interiorizar:

• No expongas credenciales: nunca pongas una clave, un token o una contraseña directa en la línea de comandos, porque aparece en el historial del shell (history) y en los logs del sistema. Variable de entorno o archivo con permisos restringidos, siempre.
• Ojo con -k: la opción -k desactiva la verificación del certificado TLS. Sirve solo para pruebas en entornos de desarrollo; nunca la uses contra servidores de producción.
• Cuidado con los parámetros sensibles en la URL: si una URL lleva un token (?token=...), queda registrada en los logs del servidor y de los proxies intermedios. Envía los datos sensibles en el cuerpo de la petición con -d o --data-urlencode, nunca en la URL.
• No pongas -X cuando no lo necesitas: si usas -d, curl ya usa el método POST por defecto. Enviar -X GET con datos no tiene sentido y confunde.

Colofón: un cheatsheet de emergencia

Estas son las opciones que hay que saber sí o sí:

• curl URL — descargar en la salida el cuerpo de una petición.
• -o archivo / -O — guardar con nombre o con el nombre original.
• -L — seguir redirecciones.
• -I — solo cabeceras (HEAD).
• -s — modo silencioso.
• -d 'datos' — enviar datos de formulario o JSON, método POST.
• -H "Cabecera: valor" — añadir cabecera.
• -w "%{http_code}" — escribir variables de la respuesta.
• -u usuario:pass — autenticación básica.
• --limit-rate y -C — control y reanudación de descargas.

Con esto ya puedes: verificar un sitio en una línea, probar APIs sin salir del terminal, automatizar descargas y montar tus primeras comprobaciones. Y cuando dudes de cómo funciona una opción, el propio curl te saca de dudas con curl --help all o la documentación oficial en curl.se/docs/manpage.html, que siempre está al día.