curl - Descargar y enviar datos por HTTP
El comando curl se comunica con servidores web mediante HTTP y HTTPS desde el Símbolo del sistema. Permite descargar páginas web y archivos, llamar a APIs web y comprobar códigos de estado HTTP sin usar un navegador.
curl.exe viene incluido en Windows 10 versión 1803 y posteriores, y en Windows 11, por lo que puedes usarlo sin instalar nada.
Sintaxis básica de curl
curl [opciones] URLSi solo indicas una URL, curl muestra en la consola, tal cual, lo que devuelve el servidor.
curl https://example.com
Al ejecutar where curl se muestra una ruta como C:\Windows\System32\curl.exe, y curl --version muestra la versión. Si no se encuentra, es posible que tengas una versión anterior a Windows 10 1803. Si tienes instalado Git for Windows u otro software similar, puede aparecer primero otro curl. Para where, consulta
En Windows PowerShell 5.1, curl es un alias del cmdlet Invoke-WebRequest, y tanto las opciones como los resultados difieren de este artículo. PowerShell 7 y posteriores ya no tienen este alias, pero escribir curl.exe con la extensión ejecuta el curl real en cualquier versión. Las reglas de comillas también son distintas en PowerShell. El Símbolo del sistema no tiene este problema.
Guardar en un archivo (-o / -O)
Para guardar el contenido descargado en un archivo, indica el destino con -o.
curl -o page.html https://example.comPara reutilizar el nombre de archivo del final de la URL, usa -O en mayúscula.
curl -O https://example.com/files/report.pdfEn este ejemplo, report.pdf se guarda en el directorio actual. Consulta también
Al guardar con -o o -O, si ya existe un archivo con el mismo nombre se sobrescribe sin aviso. Si lo ejecutas en una carpeta con archivos importantes, indica explícitamente la ruta de destino.
Seguir redirecciones (-L)
Las URL cortas y las de descarga a veces redirigen a otra URL. Por defecto curl no sigue la redirección, así que añade -L para obtener el destino final.
curl -L -o setup.zip https://example.com/download/latestAjustar el progreso y los errores (-s / -S / -f)
curl muestra un medidor de progreso durante la descarga. Para mantener limpio el registro de un archivo por lotes, combina las siguientes opciones.
| Opción | Descripción |
|---|---|
-s | Oculta el medidor de progreso y los mensajes de error (silencioso) |
-S | Usada con -s, muestra un mensaje solo cuando ocurre un error |
-f | Ante errores HTTP como 404 o 500, termina con error en lugar de guardar el cuerpo de respuesta |
Sin -f, una página de error 404 (una página HTML que describe el error) se guarda en el archivo como si la descarga hubiera tenido éxito. La combinación -fsSL se usa mucho en scripts.
curl -fsSL -o setup.zip https://example.com/download/latestComprobar solo los encabezados HTTP (-I)
Con -I, curl no obtiene el cuerpo y muestra solo los encabezados HTTP (estado, fecha de modificación, etc.).
curl -I https://example.com
中小企業経営者のためのRPA入門 RPA導入を成功させる方法
60分でわかる！ AIエージェント 超 入門
コマンドラインの黒い画面が怖いんです。
知識・才能ゼロでもらく～に月10万円稼ぐ! よくわかるAI副業超入門
Puedes comprobar si un sitio responde y qué tamaño tiene un archivo sin descargarlo. La salida varía según el servidor.
Llamar a una API web (-H / -d / -X)
GET con un encabezado (-H)
-H añade cualquier encabezado HTTP. Se usa, por ejemplo, para enviar un token de API.
curl -H "Authorization: Bearer %API_TOKEN%" https://api.example.com/v1/itemsEscribir el token directamente en el comando puede filtrarlo a través del historial de comandos o al compartir pantalla. Se recomienda guardarlo en una variable de entorno y referenciarlo, como en este ejemplo. Para las variables de entorno, consulta
.Enviar datos con POST (-d)
Al indicar datos con -d, el método pasa a ser POST automáticamente. Para enviar JSON, añade también un encabezado Content-Type.
curl -X POST -H "Content-Type: application/json" -d "{\"name\":\"sample\",\"count\":3}" https://api.example.com/v1/itemsEn el Símbolo del sistema, solo las comillas dobles " pueden delimitar una cadena, por lo que las comillas dobles dentro del JSON se escapan como \".
Si el JSON es largo, guárdalo en un archivo y cárgalo con @nombre_de_archivo. Así evitas el trabajo de escapar y los errores de escritura.
curl -X POST -H "Content-Type: application/json" -d @data.json https://api.example.com/v1/itemsAl indicar -d, el método ya es POST, así que -X POST se puede omitir. Úsalo para otros métodos, como -X PUT o -X DELETE.
Si escribes directamente en el Símbolo del sistema caracteres no ASCII, como japonés, pueden enviarse con la codificación corrupta por la página de códigos. Para datos con esos caracteres, guárdalos como UTF-8 y pásalos con -d @data.json. Consulta
Obtener el código de estado HTTP (-w)
-w (write-out) muestra información sobre la transferencia. %{http_code} es el código de estado HTTP.
curl -s -o NUL -w "%{http_code}" https://example.com-o NUL descarta el cuerpo (NUL es un nombre de dispositivo especial que descarta todo lo que se escribe en él).
En un archivo por lotes, % tiene un significado especial, por lo que -w "%{http_code}" debe escribirse como -w "%%{http_code}". Al escribir directamente en el Símbolo del sistema, basta con un solo %.
Configurar tiempos de espera y reintentos
En una red inestable, fijar un tiempo de espera y un número de reintentos evita que el proceso se quede bloqueado.
| Opción | Descripción |
|---|---|
--max-time segundos | Límite de tiempo de toda la operación |
--connect-timeout segundos | Límite de tiempo para establecer la conexión |
--retry cantidad | Número de reintentos ante errores transitorios |
curl -fsSL --connect-timeout 10 --max-time 60 --retry 3 -o setup.zip https://example.com/download/latestEjemplo: comprobar si la descarga tuvo éxito
curl devuelve el código de salida 0 si tiene éxito y uno distinto de 0 si falla. Combinado con -f, también los errores HTTP como 404 se tratan como fallos.
@echo off
setlocal
set "url=https://example.com/files/report.pdf"
set "dest=%USERPROFILE%\Downloads\report.pdf"
curl -fsSL --retry 3 -o "%dest%" "%url%"
if errorlevel 1 (
echo La descarga ha fallado.
exit /b 1
)
echo Descarga completada: "%dest%"
endlocalLos códigos de salida se explican en
. Con-f, curl devuelve el código de salida 22 ante un error HTTP.
Si una URL contiene &, como en ?a=1&b=2, el Símbolo del sistema interpreta & como separador de comandos. Encierra siempre la URL entre comillas dobles. En un archivo por lotes, una secuencia con codificación porcentual como %20 en la URL debe escribirse como %%20.
-k omite la verificación del certificado HTTPS, pero entonces no te darás cuenta si la comunicación es interceptada o manipulada. Úsalo solo si entiendes el riesgo, por ejemplo en un entorno de pruebas interno, y normalmente no lo añadas.
Resumen
| Objetivo | Ejemplo |
|---|---|
| Mostrar el contenido en pantalla | curl URL |
| Guardar con un nombre indicado | curl -o nombre URL |
| Guardar con el nombre de la URL | curl -O URL |
| Seguir redirecciones | curl -L URL |
| Comprobar solo los encabezados | curl -I URL |
| Enviar JSON | curl -H "Content-Type: application/json" -d "..." URL |
| Obtener el código de estado | curl -s -o NUL -w "%{http_code}" URL |