curl para principiantes: tu primer paso en el mundo de las peticiones HTTP

curl — una utilidad de línea de comandos para transferir datos por URL. Envía una solicitud al servidor y muestra la respuesta: una página HTML, JSON de una API, cabeceras o un archivo. El nombre se interpreta como Client URL. Además de HTTP y HTTPS, curl funciona con FTP, SFTP, SMTP, IMAP y otros protocolos.

curl está en casi cualquier sistema Linux y macOS, y viene incluido en Windows 10 y 11. Se usa para:

• comprobar APIs y servicios web sin navegador;
• descargar archivos en scripts;
• comprobar la disponibilidad del sitio, redirecciones y certificado;
• averiguar dónde se pierde tiempo al cargar una página;
• enviar correos de prueba vía SMTP.

Primera solicitud

Sin parámetros curl realiza una solicitud GET y muestra el cuerpo de la respuesta en la terminal:

curl https://example.com

Opciones principales

Descripciones — según la guía oficial de curl.

La opción -k desactiva la verificación del certificado TLS, y la conexión deja de estar protegida contra suplantación. Es admisible solo para diagnóstico en un entorno propio; en scripts y entornos de producción no debe usarse.

La combinación -sS es útil en scripts: el progreso no ensucia la salida y los errores se ven. Para descargar en scripts normalmente se escribe curl -fsSL: sin progreso, con mensaje de error, siguiendo redirecciones y con código de salida no nulo si el servidor respondió error.

Cabeceras y redirecciones

Ver solo las cabeceras de la respuesta:

curl -I https://example.com

Comprobar hacia dónde apunta la cadena de redirecciones y ver las cabeceras de cada respuesta:

curl -sIL http://example.com

Salida detallada con detalles de la conexión TLS — lo primero que hay que hacer si la solicitud se comporta de forma extraña:

curl -v https://example.com -o /dev/null

Solicitudes a la API

Solicitud GET con cabecera de autorización:

curl -s -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/items

POST con datos de formulario:

curl -d "name=mike&age=30" https://api.example.com/register

Si se indica -d, el método POST se selecciona automáticamente; no es necesario añadir -X POST.

POST con JSON:

curl --json '{"name": "mike", "age": 30}' https://api.example.com/users

En versiones antiguas de curl, donde aún no existe --json, lo mismo se escribe así:

curl -H "Content-Type: application/json" -d '{"name": "mike", "age": 30}' https://api.example.com/users

PUT y DELETE:

curl -X PUT --json '{"age": 31}' https://api.example.com/users/42
curl -X DELETE https://api.example.com/users/42

Autenticación básica:

curl -u admin:contraseña https://example.com/admin/

Si se indica solo el usuario (-u admin), curl pedirá la contraseña de forma interactiva y no quedará en el historial de comandos.

Descarga y subida de archivos

# guardar con el nombre del URL
curl -O https://example.com/file.zip

# guardar con un nombre propio
curl -o backup.zip https://example.com/file.zip

# enviar archivo mediante formulario (multipart/form-data)
curl -F "file=@report.pdf" https://example.com/upload

# subir archivo con método PUT
curl -T report.pdf https://example.com/files/report.pdf

Cuánto tiempo tarda una solicitud

La opción -w muestra variables de servicio después de ejecutar la solicitud. Así puedes entender en qué etapa se pierde tiempo:

curl -o /dev/null -s -w "DNS: %{time_namelookup}\nTCP: %{time_connect}\nTLS: %{time_appconnect}\nPrimer byte: %{time_starttransfer}\nTotal: %{time_total}\nCódigo: %{http_code}\n" https://example.com

Todos los valores están en segundos desde el inicio de la solicitud. Si el tiempo de DNS es grande, el problema está en el resolvedor; si el tiempo hasta el primer byte es alto con una conexión rápida, la propia aplicación responde lentamente. Más sobre búsqueda de problemas de red — en el artículo «Solución de problemas de red: utilidades de diagnóstico».

Código de respuesta por separado, por ejemplo para monitorización en un script:

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

Tiempos de espera, reintentos y proxies

# no esperar más de 5 segundos para la conexión, ni más de 20 para toda la operación
curl --connect-timeout 5 -m 20 https://example.com

# reintentar hasta tres veces en errores temporales
curl --retry 3 https://example.com

# solicitud a través de proxy HTTP o SOCKS5
curl -x http://proxy.example.com:3128 https://example.com
curl -x socks5h://127.0.0.1:1080 https://example.com

El esquema socks5h:// significa que el propio proxy resuelve el nombre del servidor, y no tu equipo.

Protocolos de correo

Envío de correo por SMTP

curl --url "smtp://smtp.example.com:587" \
  --ssl-reqd \
  --mail-from "sender@example.com" \
  --mail-rcpt "recipient@example.com" \
  --upload-file email.txt \
  --user "username:password"

• --ssl-reqd — exigir cifrado (STARTTLS);
• --mail-from y --mail-rcpt — remitente y destinatario;
• --upload-file — archivo con el correo: encabezados From, To, Subject, una línea en blanco y el texto.

Ver carpetas vía IMAP

curl --url "imaps://imap.example.com" \
  --user "username:password" \
  -X 'LIST "" "*"'

Errores comunes

• Olvidar -L. El servidor responde con una redirección y curl muestra una respuesta vacía o la página «Moved».
• Usar -k en scripts de producción. El script deja de detectar la suplantación del certificado. Es mejor corregir la cadena de certificados en el servidor o indicar tu certificado raíz con --cacert.
• Contraseñas y tokens en la línea de comandos. Quedan en el historial del shell y son visibles en la lista de procesos. Es mejor pasar los tokens vía variables de entorno o un archivo (-H @headers.txt).
• No usar -f en scripts. Sin él, una respuesta 404 o 500 se considera una petición exitosa, y el script seguirá trabajando con un «archivo» que en realidad contiene la página de error.

curl complementa convenientemente las herramientas de desarrollador del navegador: su comando es fácil de guardar, repetir e insertar en un script o tarea de CI.

Cómo buscar la causa de un problema con curl — enviar la solicitud a un servidor concreto evitando DNS, rastrear la cadena de redirecciones, analizar en qué etapa se pierde tiempo — está descrito en el artículo «Depuración HTTP con curl». La comprobación de certificados y TLS — en «Depuración TLS: curl y openssl s_client».