Generador y constructor de comandos cURL

¿Qué es un comando curl?

# Plain GET — curl defaults to GET
curl https://api.example.com/users

# GET with a Bearer token (auth is just a header)
curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

# POST a JSON body — note the Content-Type header
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

# Multipart file upload — '@' reads the file from disk
curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

Características principales

Alternativas a curl y clientes HTTP

Ejemplos de comandos curl

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

curl https://api.example.com/me \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada","role":"admin"}'

curl -X POST https://api.example.com/login \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=ada&password=s3cret'

curl -X POST https://api.example.com/upload \
  -F 'file=@report.pdf' \
  -F 'title=Q3 report'

curl -L -o archive.zip \
  https://example.com/files/archive.zip

curl -u ada:s3cret \
  https://api.example.com/private

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

Cómo construir un comando curl

1. 1

   Elige el método HTTP

   Selecciona GET, POST, PUT, PATCH, DELETE, HEAD u OPTIONS. curl usa GET por defecto; elegir POST u otro verbo añade -X MÉTODO al comando generado. O pulsa un preset para establecer el método y un cuerpo compatible con un solo clic.

2. 2

   Introduce la URL y los parámetros de consulta

   Escribe la URL de la petición (p. ej. https://api.example.com/users). Añade parámetros de consulta como pares clave/valor y la herramienta los codifica en URL y añade ?clave=valor&… a la URL automáticamente — no es necesaria ninguna codificación manual.

3. 3

   Añade cabeceras y autenticación

   Añade cabeceras de petición como pares clave/valor y luego elige un esquema de autenticación: Ninguna, token Bearer, Basic (usuario/contraseña) o una cabecera personalizada de API-key. Se genera la cabecera Authorization o personalizada correcta en el formato exacto que espera el servidor.

4. 4

   Configura el cuerpo de la petición

   Para POST/PUT/PATCH, elige un tipo de cuerpo: pega JSON sin formato (la cabecera Content-Type se añade por ti), construye campos de formulario urlencoded, o ensambla una subida multipart y convierte cualquier campo en archivo con el prefijo @.

5. 5

   Activa las opciones

   Activa los indicadores que necesites — seguir redirecciones (-L), TLS inseguro (-k), verbose (-v), incluir cabeceras (-i), comprimido (--compressed), salida a archivo (-o), tiempo de espera de conexión o proxy (-x). Cada activación actualiza el comando en tiempo real.

6. 6

   Copia, exporta o restablece

   Copia el comando terminado, usa Exportar .sh para descargarlo como script, o Restablecer para limpiar el formulario. Usa el interruptor Multilínea para alternar entre salida en una sola línea y con continuaciones de barra invertida antes de copiar.

Errores comunes en curl

# Intentaba un PATCH, pero -d solo implica POST
curl -d '{"role":"admin"}' \
  https://api.example.com/users/7

# Establece el verbo explícitamente
curl -X PATCH -d '{"role":"admin"}' \
  -H 'Content-Type: application/json' \
  https://api.example.com/users/7

# El servidor recibe urlencoded, no JSON — 400/415
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

# Declara el tipo de contenido JSON
curl -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"name":"Ada"}'

# $name es expandido por el shell a cadena vacía
curl -d "{\"user\":\"$name\"}" \
  https://api.example.com/users

# Las comillas simples envían el cuerpo literalmente
curl -d '{"user":"$name"}' \
  https://api.example.com/users

# -d convierte esto en POST, no en GET
curl -d 'page=2&limit=50' \
  https://api.example.com/users

# La cadena de consulta en la URL lo mantiene como GET
curl 'https://api.example.com/users?page=2&limit=50'

:: cmd.exe — la barra invertida no es carácter de continuación
curl -X POST https://api.example.com/users \
  -d '{"name":"Ada"}'

:: cmd.exe — una línea, o usa ^ para continuar
curl -X POST https://api.example.com/users -d "{\"name\":\"Ada\"}"

# El espacio divide el argumento — curl ve dos args
curl https://api.example.com/search?q=hello world

# Codifica el espacio (o entrecomilla toda la URL)
curl 'https://api.example.com/search?q=hello%20world'

Casos de uso habituales

Prueba de REST API

Construye y envía peticiones contra un endpoint REST sin salir de la terminal: establece el método, pega un token Bearer, envía un cuerpo JSON y lee la respuesta. La forma más rápida de confirmar que una API funciona antes de escribir el código del cliente.

Reproducir una petición desde la documentación

La documentación de la API muestra endpoints y parámetros, pero rara vez un comando completo listo para copiar. Rellena el método, la URL, las cabeceras y la autenticación aquí y obtén un comando curl que funciona tal cual — sin luchar con el entrecomillado ni cabeceras Content-Type faltantes.

Scripts de prueba de humo en CI/CD

Genera un comando curl para una comprobación de estado o una prueba de humo post-despliegue, luego usa Exportar .sh para añadirlo a un pipeline. Añade --connect-timeout y --max-time para que un endpoint colgado no pueda bloquear la compilación, y comprueba los códigos de estado con -w.

Subida y descarga de archivos

Ensambla una subida multipart/form-data con -F campo=@archivo, o construye una descarga con -L -o nombre_de_archivo que sigue las redirecciones hacia un CDN. Codifica primero los nombres de archivo o valores de consulta complicados con nuestro codificador de URL.

Depuración de webhooks

Reproduce un payload de webhook enviando el mismo cuerpo JSON que el proveedor envía, con las cabeceras de firma y Content-Type correctas. Reproduce la petición exacta localmente para depurar por qué tu manejador la rechazó.

Informes de errores reproducibles

Pega un único comando curl autocontenido en un informe de error o PR para que cualquiera pueda reproducir la petición exacta — método, cabeceras, marcador de autenticación y cuerpo. Mucho más claro que describir la petición en prosa.

Aprender los indicadores de curl

Ve cómo cada elección del formulario se corresponde con un indicador real — elige autenticación Basic y observa cómo aparece -u, añade un cuerpo JSON y ve cómo se adjunta la cabecera Content-Type. Una forma práctica de aprender la sintaxis, combinada con nuestra hoja de referencia de curl.

Preparar una petición para convertir a código

Construye y verifica la petición como curl primero, luego tradúcela al cliente HTTP de tu aplicación. La próxima pestaña Convertir transformará un comando curl pegado en fetch, requests, Go, PHP, Ruby y Node.js — comienza desde un comando curl que sabes que funciona.

Referencia de indicadores y sintaxis de curl

Entrecomillado y escape del shell

La herramienta envuelve los valores entre comillas simples, la forma más segura en shells POSIX porque nada dentro de una cadena entre comillas simples se expande. Una comilla simple literal dentro de un valor se emite como la secuencia '\'' (cierra comilla, comilla escapada, reabre comilla). En cmd.exe cambia a comillas dobles; Git Bash y WSL ejecutan los comandos con comillas simples generados sin cambios.

-d vs --data-raw vs --data-binary

-d/--data elimina los saltos de línea y retornos de carro del cuerpo — válido para pares clave=valor, con pérdida para contenido multilínea. --data-raw es lo mismo pero no tratará un @ inicial como nombre de archivo. --data-binary envía los bytes exactamente como se proporcionan (usa @archivo para subir contenidos de archivo brutos). Los tres implican POST salvo que se anule el método.

Multipart (-F) vs urlencoded (-d)

-F campo=valor produce multipart/form-data con un límite generado — necesario para subidas de archivos (-F archivo=@ruta) y formularios mixtos de archivos y texto. -d campo=valor produce application/x-www-form-urlencoded, una cadena única unida por &. Nunca establezcas Content-Type manualmente para multipart; curl calcula el límite y establece la cabecera por sí mismo.

Codificación de la cabecera de autenticación

La autenticación Bearer envía Authorization: Bearer <token> literalmente (RFC 6750). La autenticación Basic de -u usuario:contraseña se codifica en Base64 como Authorization: Basic <base64> al transmitirla — es codificación, no cifrado, así que usa HTTPS. Una API key es cualquier cabecera personalizada que requiera el servicio, p. ej. X-API-Key: <valor>.

Codificación de la cadena de consulta

Los parámetros de consulta añadidos en el constructor se codifican en porcentaje y se añaden como ?clave=valor&clave2=valor2. Los caracteres reservados (espacios, &, =, #) se escapan para que la URL sea válida. Para los campos del cuerpo que deban codificarse, el propio --data-urlencode de curl gestiona la codificación en el momento de la petición.

Comportamiento de las redirecciones (-L)

Sin -L, curl imprime una respuesta 301/302 y se detiene. Con -L sigue la cabecera Location hasta la URL final. Ten en cuenta que curl elimina la cabecera Authorization cuando una redirección cruza a un host diferente (un comportamiento de seguridad por defecto); usa --location-trusted solo cuando entiendas las implicaciones.

Respuestas comprimidas

--compressed añade una cabecera Accept-Encoding que anuncia compatibilidad con gzip/deflate/brotli y descomprime la respuesta de forma transparente, ahorrando ancho de banda. El cuerpo descodificado es idéntico al de una petición sin comprimir — es puramente una optimización de la transferencia, seguro de activar en la mayoría de llamadas a la API.

Salida: -o vs -O

-o nombre_de_archivo escribe el cuerpo de la respuesta en un archivo que tú nombras; -O lo guarda con el nombre de archivo remoto de la ruta de la URL. Ambos suprimen el volcado normal por stdout. Combínalos con -L para que las redirecciones se resuelvan al activo real antes de escribir el archivo.

Buenas prácticas para peticiones curl

Nunca codifiques secretos en comandos compartidos

Un comando curl que pegas en un PR, un ticket o un chat será leído por otros e indexado por herramientas. Reemplaza los tokens y contraseñas por un marcador (YOUR_TOKEN) o referencia una variable de entorno (-H "Authorization: Bearer $API_TOKEN"). Para credenciales largas, curl puede leer una cabecera de un archivo con -H @archivocabecera para que el secreto nunca aparezca en el historial del shell.

Prefiere --data-binary @archivo para payloads binarios

Cuando el cuerpo es un archivo cuyos bytes importan — una imagen, un payload firmado, JSON donde el espacio en blanco es significativo — usa --data-binary @archivo en lugar de -d @archivo. El -d simple elimina los saltos de línea y retornos de carro, corrompiendo silenciosamente el contenido binario y multilínea. --data-binary envía el archivo exactamente como está en el disco.

Entrecomilla los valores de las cabeceras

Envuelve siempre los valores de -H entre comillas: -H 'Content-Type: application/json'. Sin entrecomillar, el espacio después de los dos puntos divide el argumento y curl ve una cabecera malformada. Las comillas simples también evitan que el shell expanda $, * y otros caracteres especiales dentro del valor — exactamente lo que esta herramienta emite por defecto.

Usa --compressed para ahorrar ancho de banda

Añade --compressed en llamadas a la API y descargas para solicitar codificación gzip/brotli y que curl descomprima de forma transparente. Para las API con mucho JSON, esto puede reducir el tamaño de la transferencia en un 70-90% sin ningún cambio en la respuesta que ves — una mejora gratuita en scripts que sondean endpoints repetidamente.

Fija los tiempos de espera en los scripts

En cualquier contexto automatizado, añade --connect-timeout y --max-time para que un endpoint lento o colgado no pueda bloquear un pipeline indefinidamente. Una comprobación de estado con --max-time 10 falla rápido y permite que tu CI continúe. Combínalo con --retry N para absorber fallos de red transitorios sin rendirse de inmediato.

Verifica con -v antes de automatizar

Antes de incluir un comando curl en un script o trabajo cron, ejecútalo una vez con -v para ver la línea de petición exacta, las cabeceras y el apretón de manos TLS. Es la forma más rápida de detectar un método incorrecto, un Content-Type faltante o una cabecera de autenticación que no se adjuntó — depura interactivamente y luego elimina -v para producción.

Preguntas frecuentes