Constructor de Comando curl

El Constructor de Comandos curl genera comandos curl completos y correctamente escapados a través de un formulario interactivo, permitiéndote configurar método HTTP, headers, autenticación, cuerpo de petición y opciones sin memorizar la extensa sintaxis de banderas de curl. Selecciona POST, agrega un cuerpo JSON y un Bearer token, y obtén un comando listo para pegar como curl -X POST -H "Authorization: Bearer eyJ..." -H "Content-Type: application/json" -d '{"name":"Alice"}' https://api.example.com/users.

Entendiendo curl

curl es la navaja suiza de HTTP. Viene incluido con virtualmente cada distribución Linux, cada instalación de macOS, y está disponible en Windows. Cuando necesitas probar un endpoint de API, reproducir un reporte de error, verificar headers de respuesta o confirmar que un servidor es alcanzable, curl es usualmente el camino más rápido de la pregunta a la respuesta. Se ejecuta en cualquier terminal, no requiere configuración, y produce salida que puedes redirigir a otras herramientas, guardar en archivos o incluir en scripts.

El desafío con curl es su enorme amplitud. La herramienta soporta más de 200 banderas de línea de comandos, cubriendo todo desde peticiones GET básicas hasta autenticación con certificado de cliente, túneles de proxy y descargas reanudables. Para pruebas de API cotidianas, necesitas quizás una docena de estas banderas, pero saber cuáles y acertar con la sintaxis -- especialmente las reglas de comillas que difieren entre bash, zsh, PowerShell y CMD -- requiere práctica. Es fácil olvidar si la bandera de autenticación es -u o --user, si el cuerpo va después de -d o --data, y si los cuerpos JSON necesitan comillas simples o comillas dobles escapadas.

Este constructor maneja la sintaxis por ti. Completas las partes que conoces -- URL, método, headers, cuerpo, credenciales de autenticación -- y genera un comando correctamente formateado y debidamente escapado para tu plataforma. Puedes copiarlo directamente a tu terminal y ejecutarlo. Con el tiempo, construir comandos interactivamente y estudiar la salida es una de las mejores formas de aprender la sintaxis de curl, porque puedes ver cómo cada campo del formulario se mapea a una bandera y cómo funciona el entrecomillado para tu shell.

Cómo construir un comando curl

1. Ingresa la URL de destino para tu petición HTTP.
2. Selecciona el método HTTP (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS).
3. Agrega headers personalizados (por ejemplo, Content-Type: application/json, Authorization: Bearer <token>).
4. Configura el cuerpo de la petición para peticiones POST/PUT/PATCH (JSON, datos de formulario o texto sin formato).
5. Configura opciones como seguir redirecciones, timeout o salida detallada.
6. Copia el comando generado para tu shell (Unix/macOS o Windows PowerShell).

Ejemplos de comandos curl

Petición GET simple

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

Petición POST con cuerpo JSON

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

Petición autenticada con Bearer token

curl https://api.example.com/account \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Petición PUT con Basic Auth

curl -X PUT https://api.example.com/settings \
  -u "admin:password123" \
  -H "Content-Type: application/json" \
  -d '{"notifications": true, "theme": "dark"}'

POST con datos de formulario (URL-Encoded)

curl -X POST https://example.com/login \
  -d "username=alice&password=secret123"

Petición con múltiples opciones

curl -X DELETE https://api.example.com/posts/99 \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "X-Request-ID: req-abc-123" \
  -L \
  --max-time 30 \
  -w "\n%{http_code}\n"

Cuándo usar el constructor de comandos curl

• Pruebas de API durante el desarrollo -- Construye rápidamente peticiones para probar endpoints sin escribir código de cliente o cambiar a una herramienta con interfaz gráfica.
• Generación de ejemplos de documentación -- Construye comandos curl correctos y listos para copiar y pegar para documentación de API y archivos README.
• Creación de reportes de errores reproducibles -- Genera un comando curl independiente que reproduce un problema, facilitando que otros desarrolladores lo prueben.
• Aprendizaje de la sintaxis de curl -- Construye comandos interactivamente y estudia las banderas generadas para aprender las opciones de curl con ejemplos.
• Generación de comandos multiplataforma -- Obtén comandos correctamente escapados tanto para shells Unix/macOS (usando comillas simples) como para Windows PowerShell (usando comillas dobles escapadas).
• Compartir casos de prueba de API -- Produce un comando autocontenido que cualquiera con curl puede ejecutar para verificar el comportamiento.

Referencia de banderas de curl

Banderas comunes

Banderas de timeout y reintentos

Banderas de cuerpo y contenido

Escapado y entrecomillado del shell

El constructor maneja las diferencias complicadas entre shells:

Unix/macOS (bash, zsh) -- Usa comillas simples para cuerpos JSON para evitar interpretar $ y !:

curl -d '{"price": "$9.99"}' https://api.example.com/order

Windows PowerShell -- Usa comillas dobles escapadas ya que PowerShell no soporta la interpolación de cadenas con comillas simples de la misma manera:

curl -d "{\"price\": \"$9.99\"}" https://api.example.com/order

Windows CMD -- Usa comillas dobles con comillas internas escapadas:

curl -d "{\"price\": \"$9.99\"}" https://api.example.com/order

Consejos prácticos para usar curl

Una de las características más útiles pero poco usadas de curl es la bandera -w (write-out). Te permite imprimir información específica sobre la petición después de que se completa, como el código de estado HTTP, tiempo total, tiempo de resolución DNS o el tamaño de la respuesta. Para pruebas rápidas de API, curl -s -o /dev/null -w "%{http_code}\n" https://api.example.com/health te da solo el código de estado sin salida del cuerpo -- perfecto para scripts de verificación de salud. También puedes usar -w "%{time_total}\n" para medir tiempos de respuesta desde la línea de comandos sin instalar herramientas adicionales.

Cuando depuras problemas de SSL/TLS, la bandera -v (verbose) de curl muestra todo el handshake TLS incluyendo la cadena de certificados, versión del protocolo y suite de cifrado. Esto es invaluable para diagnosticar errores de certificados, probar rotación de certificados o verificar que un servidor soporta una versión específica de TLS. Combina -v con --tlsv1.2 o --tlsv1.3 para forzar una versión específica de TLS y probar compatibilidad.

Para flujos de trabajo de pruebas de API, considera guardar los comandos curl usados frecuentemente como scripts de shell o alias. Un comando como curl -s -H "Authorization: Bearer $API_TOKEN" -H "Content-Type: application/json" https://api.example.com/v1/ es tedioso de escribir repetidamente. Guardarlo como una función o alias con la URL base y los headers comunes significa que solo necesitas agregar el endpoint específico y el cuerpo para cada prueba. Muchos desarrolladores mantienen una colección de comandos curl en un archivo requests.sh en su proyecto, que también sirve como documentación viva de la API.

Preguntas frecuentes

¿Cómo envío un archivo como cuerpo de la petición?

Usa el prefijo @ con -d para leer el cuerpo de un archivo: curl -X POST -d @payload.json -H "Content-Type: application/json" https://api.example.com/upload. Para carga de archivos multipart, usa -F "[email protected]".

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

-d envía el cuerpo como un solo bloque (usualmente application/x-www-form-urlencoded o application/json). -F envía multipart/form-data, que está diseñado para cargas de archivos y campos de formulario mixtos. Usa -F cuando necesites cargar archivos junto con datos de formulario.

¿Debería usar -k / --insecure para omitir la verificación TLS?

Solo en entornos de desarrollo con certificados autofirmados. Nunca uses -k en scripts de producción o al enviar credenciales, ya que deshabilita la verificación de certificados y abre la conexión a ataques de intermediario.

¿Cómo veo los headers de respuesta junto con el cuerpo?

Usa -i (include) para imprimir los headers de respuesta antes del cuerpo, o -v (verbose) para ver tanto los headers de petición como de respuesta junto con los detalles del handshake TLS. Para solo los headers sin el cuerpo, usa -I (petición HEAD) o -o /dev/null -v para descartar el cuerpo pero mostrar la salida detallada.

¿Puede curl seguir redirecciones automáticamente?

Sí. Usa -L (o --location) para seguir redirecciones 3xx. Por defecto, curl se detiene en la primera redirección y muestra la respuesta de redirección. Con -L, sigue la cadena hasta llegar a una respuesta final. Puedes limitar el número de redirecciones con --max-redirs 5.

¿Cómo manejo cookies en curl?

Usa -b para enviar cookies y -c para guardar cookies recibidas del servidor. Por ejemplo, curl -c cookies.txt https://example.com/login -d "user=alice" guarda las cookies de inicio de sesión, y curl -b cookies.txt https://example.com/dashboard las envía de vuelta. Esto es útil para probar flujos de autenticación que dependen de cookies de sesión.

Herramientas relacionadas

• HTTP Header Formatter - Formatea headers para usar en comandos curl
• HTTP Status Code Lookup - Busca códigos de estado devueltos por peticiones curl
• CORS Header Explainer - Entiende los headers CORS al probar APIs cross-origin
• Query String Parser/Builder - Construye query strings para agregar a URLs de peticiones curl
• User-Agent Parser - Analiza cadenas User-Agent para establecer valores personalizados en peticiones curl