autodl-cli

No oficial. Este proyecto no está afiliado, respaldado ni patrocinado por AutoDL. "AutoDL" se usa únicamente para identificar la plataforma con la que esta herramienta se comunica.

Gestiona instancias de GPU de AutoDL desde la línea de comandos — y deja que tu agente de codificación también lo haga.

Construido sobre la API oficial abierta de AutoDL, por lo que el token de desarrollador permanece válido indefinidamente y nada se rompe cuando se rediseña la consola web.

简体中文

Por qué

Cuando un agente de IA necesita una caja de GPU a mitad de tarea, no tiene forma de conseguirla: las instancias de AutoDL se crean haciendo clic en una consola web. Esto le da al agente tres vías de acceso, todas respaldadas por el mismo núcleo:

Cada comando habla --json con un esquema estable y un código de salida documentado, para que un agente pueda ramificar según el resultado sin analizar prosa.

Related MCP server: lab-ops

Instalación

npm install -g @minatoaqukin/autodl-cli   # then: autodl <command>
npx @minatoaqukin/autodl-cli <command>    # or without installing

Requiere Node.js 22+.

El panel

autodl tui     # or just `autodl` in an interactive terminal

En una máquina sin token aún, se abre una pantalla de inicio de sesión que ofrece dos cosas: configurar un token o salir. Pega el token, se verifica contra la API antes de guardarse, y aterrizas en el panel. Una vez configurado, autodl entra directamente.

Una tabla en vivo de tus instancias: estado, GPU, región, cuánto tiempo ha estado encendida cada una y aproximadamente cuánto ha costado, y cuánto TTL queda. Teclas: ↑↓ mover, Enter detalle, s iniciar, x detener, c copiar el comando SSH al portapapeles, Ctrl+D liberar, g stock de GPU, n nueva instancia, r refrescar, q salir. Liberar está en Ctrl+D en lugar de una tecla simple porque borra la instancia permanentemente.

Llena la terminal y muestra tu ID de cuenta y saldo en el encabezado. Copiar con c pone solo el comando SSH en el portapapeles — nunca la contraseña de root, que cualquier proceso podría leer. Donde no existe un helper de portapapeles (sesiones SSH, contenedores), recurre a OSC 52 y lo dice, ya que la terminal nunca confirma.

Se ejecuta en la pantalla alternativa de la terminal, por lo que posee un lienzo fijo en lugar de desplazarse debajo de lo que ya estaba allí, y al salir restaura tu prompt y el scrollback sin tocar.

Existe porque AutoDL factura según el estado de encendido: el error costoso no es un comando equivocado, es una instancia que nadie recordó detener. Dejar esto abierto lo hace visible.

Dos restricciones de honestidad deliberadas. Una tarifa solo se puede conocer a partir de la instantánea de una instancia en ejecución, por lo que una instancia detenida muestra tiempo transcurrido y sin dinero — inventar un número sería peor que no mostrar ninguno. Y mientras una tarifa aún se está cargando, el total lo dice en lugar de informar de menos silenciosamente.

La TUI nunca se ejecuta en una tubería, en CI, o bajo --json: sale con código 2 y una explicación en lugar de tomar el control de una terminal que no está allí. Un autodl simple fuera de una terminal interactiva aún imprime ayuda exactamente como antes.

Configuración

La API oficial necesita un token de desarrollador de una cuenta verificada de identidad (个人或企业实名认证). Obténlo desde la consola de AutoDL → 设置 → 开发者 Token.

autodl login              # verifies the token, then saves it with 0600 permissions
autodl account            # balance, vouchers, lifetime spend

Precedencia del token: --token › AUTODL_TOKEN › ~/.config/autodl-cli/config.json.

Inicio rápido

# Rent a GPU that shuts itself off after two hours, and wait until it's ready
autodl create --gpu 4090 --ttl 2h --wait

# Work with it
autodl ls
autodl ssh pro-76419909953e                    # interactive login
autodl exec pro-76419909953e "nvidia-smi"      # one-off command, remote exit code
autodl push pro-76419909953e ./src /root/work  # SFTP upload
autodl pull pro-76419909953e /root/work/out .  # SFTP download

# Stop paying
autodl stop pro-76419909953e
autodl rm pro-76419909953e --yes               # irreversible: wipes all data

O haz todo el proceso con un solo verbo:

autodl run "python train.py" \
  --gpu 4090 --sync ./ --pull /root/autodl-cli/checkpoints --ttl 4h

Eso crea una instancia, espera a que esté lista, sube tu código, transmite la salida del comando, descarga los resultados y apaga la instancia — incluso con Ctrl-C.

Úsalo desde un agente

Claude Code

claude mcp add autodl -- npx -y @minatoaqukin/autodl-cli mcp

Cursor / Cline / cualquier cliente MCP

{
  "mcpServers": {
    "autodl": {
      "command": "npx",
      "args": ["-y", "@minatoaqukin/autodl-cli", "mcp"],
      "env": { "AUTODL_TOKEN": "your-token" }
    }
  }
}

Herramientas expuestas: autodl_account_info, autodl_list_instances, autodl_get_instance, autodl_create_instance, autodl_power_on, autodl_power_off, autodl_release_instance, autodl_exec, autodl_upload, autodl_download, autodl_run, autodl_list_gpu_specs, autodl_list_images, autodl_save_image, autodl_sweep_expired. Además, un recurso autodl://instances.

Los valores predeterminados de MCP son deliberadamente más estrictos que los de la CLI, porque nadie está mirando: se aplica un TTL de 2 horas a menos que pidas más, liberar requiere un confirm: true explícito, y las contraseñas se devuelven redactadas a menos que se soliciten.

Shell / CI

autodl ls --json | jq -r '.data[] | select(.status=="running") | .uuid'

Desplegando un proyecto git

# Rent a box, clone, auto-install dependencies, run it, then stop the instance
autodl deploy owner/repo --gpu 4090 --start "python train.py" --ttl 4h

# Long-running service: background it and keep the instance up
autodl deploy owner/repo --gpu 4090 --start "python app.py" --detach

# Come back later — powers the same box on and `git pull`s, no rebuild
autodl deploy owner/repo --instance pro-76419909953e --start "python train.py"

deploy se diferencia de run de una manera deliberada: detiene la instancia al final en lugar de liberarla. Una instancia detenida conserva sus discos, por lo que el próximo despliegue reutiliza el entorno que ya construiste. --on-finish release opta por no hacerlo.

El código aterriza en /root/autodl-tmp/<repo> — el disco de datos. El disco del sistema de AutoDL es un 30GB fijo que también se incluye en cualquier imagen guardada; el disco de datos es separado, más rápido y expandible. La compensación que vale la pena conocer: el contenido del disco de datos no se incluye cuando guardas una imagen, así que pon el entorno en el disco del sistema y el código aquí.

Las dependencias se detectan automáticamente en este orden, el primero que coincide gana — environment.yml → requirements.txt → pyproject.toml → package-lock.json/package.json. Sobrescribe con --setup "<cmd>", o omite con --no-setup.

Los comandos remotos se ejecutan a través de un shell de inicio de sesión. Las imágenes de AutoDL mantienen python, pip y conda en /root/miniconda3/bin, que solo llegan a PATH a través del perfil de inicio de sesión — un ssh host "pip install ..." no interactivo simple sale con 127. Esto también se aplica a autodl exec, por lo que se comporta como lo hace cuando entras manualmente con autodl ssh.

Clonar desde GitHub o HuggingFace habilita automáticamente el proxy académico de AutoDL (source /etc/network_turbo). Gitee es doméstico y lo omite. --no-accel lo desactiva. AutoDL señala que el proxy es "para uso académico, sin garantía de estabilidad".

Repos privados: --git-token, o GIT_TOKEN / GITHUB_TOKEN en el entorno. El token nunca llega a una línea de registro, un mensaje de error, la salida --json, o el remoto git almacenado del checkout.

Comprobando stock de GPU

autodl stock --gpu 4090        # where are the free cards
autodl stock                   # everything, everywhere

Lee esta tabla con atención: los números son menos autoritativos de lo que parecen. Provienen del endpoint de stock de despliegue elástico de AutoDL, la única API de capacidad que existe, y no rastrea la disponibilidad de instancias Pro. Medido el 2026-08-23: reportó 140 RTX 4090D inactivas en westDC3 mientras crear una instancia Pro allí respondió "暂无库存" — y la solicitud idéntica sin restricción de región tuvo éxito, aterrizando en beijingDC2.

Dos consecuencias, ambas integradas en la herramienta:

• Crear una instancia nunca reduce regiones por sí solo. Omitir data_center_list le da a AutoDL la opción más amplia, que empíricamente tiene más éxito.

• Solo dos regiones aceptan una instancia Pro: westDC3 (西北B区) y beijingDC2 (北京B区). Las otras nueve en la tabla de stock son solo de despliegue elástico; pasar una a --region se rechaza de antemano en lugar de fallar más tarde con el opaco "请求参数错误" de AutoDL. La columna 可建Pro marca cuál es cuál.

La protección de costes

AutoDL factura puramente según el estado de encendido. Una instancia que terminó de entrenar hace una hora cuesta exactamente lo mismo que una al 100% de utilización. Esta es la forma más fácil para que un agente desatendido desperdicie dinero real, por lo que la protección está integrada en lugar de ser opcional.

Tres capas:

1. Dentro de la instancia. --ttl 2h arma un sleep && shutdown separado en la propia caja a través de start_command. Se dispara incluso si esta CLI es eliminada, tu portátil se duerme o la red muere. Esta es la capa que realmente protege tu cartera.

2. Un libro mayor local. Cada comando barre oportunistamente las instancias que han pasado su TTL y las apaga. Atrapa los casos que la capa 1 no puede — un start_command que falló silenciosamente, o un encendido manual sin temporizador nuevo.

3. Detección de inactividad. autodl guard idle <id> muestrea la utilización de GPU a través de SSH y se apaga después de una pausa sostenida.

autodl guard ttl pro-xxx 2h     # arm/re-arm on a running instance
autodl guard cancel pro-xxx     # disarm
autodl guard list               # what this machine is tracking
autodl guard sweep              # reclaim everything past its TTL now
autodl guard idle pro-xxx --threshold 5 --samples 6 --interval 1m

Una puerta de saldo también se niega a crear una instancia cuando tu cartera está por debajo de --min-balance (por defecto ¥5). AutoDL no recupera instancias en el momento en que el saldo llega a cero — las mantiene para proteger tus datos — por lo que un saldo bajo se convierte en una instancia atascada e inutilizable en lugar de un fallo limpio.

El contrato del agente

Estable a través de versiones menores. Los cambios que rompen requieren una mayor.

stdout en modo --json es JSON puro. El progreso, los avisos y las advertencias van a stderr, por lo que autodl ... --json | jq siempre es seguro.

// success
{ "ok": true, "data": { /* ... */ } }

// failure
{ "ok": false, "error": { "code": "NO_STOCK", "message": "…", "hint": "…", "requestId": "…" } }

autodl exec y autodl run en cambio salen con el código de salida del comando remoto, por lo que autodl exec box "make test" && deploy se comporta como esperarías.

Comandos

Banderas globales: --json, --yes, --token, --base-url, --lang zh|en, --verbose, --no-color, --no-sweep.

push y pull omiten .git, node_modules, __pycache__, .venv y similares, y luego aplican .autodlignore si está presente, recurriendo a .gitignore en su defecto.

SDK

import {
  AutoDLClient,
  createInstance,
  execCommand,
  powerOffInstance,
  waitForRunning,
} from "@minatoaqukin/autodl-cli";

const client = new AutoDLClient({ token: process.env.AUTODL_TOKEN! });

const uuid = await createInstance(client, {
  gpuSpec: "v-48g",
  gpuNum: 1,
  imageUuid: "base-image-l2t43iu6uk",
  cudaFrom: 118,
});

await waitForRunning(client, uuid);
const { stdout } = await execCommand(client, uuid, "nvidia-smi");
console.log(stdout);
await powerOffInstance(client, uuid);

Todo lo que se re-exporta desde la raíz del paquete es API pública. Los precios llegan en yuanes (number), las marcas de tiempo como cadenas ISO, y la forma sql.NullTime de Go se aplana a string | null.

Lo que la API oficial no puede hacer

Estos son los límites de AutoDL, no los de esta herramienta. Conocerlos de antemano ahorra mucha confusión:

• Solo pago por uso. Sin planes diarios/semanales/mensuales y sin endpoint de renovación.

• Solo instancias Pro. Las siete especificaciones en autodl gpus — las instancias estándar más baratas no son accesibles a través de la API abierta.

• Sin consulta de stock utilizable para Pro. El único endpoint de capacidad informa del stock de despliegue elástico, que demostrablemente no coincide con la disponibilidad de Pro (ver arriba). La creación es efectivamente un intento a ciegas; sin capacidad significa código de salida 6 y otra especificación que probar.

• Solo dos regiones aceptan una instancia Pro: westDC3 y beijingDC2.

• Sin arranque solo-CPU todavía. El propio texto de AutoDL es deliberadamente provisional: payload está documentado como "gpu：有卡开机, 暂不支持API以无卡模式开机" — todavía no compatible, en lugar de nunca. Confirmado en una instancia real el 2026-08-24: cpu, no_gpu, nogpu, cpu_only, cpu-only y none devuelven todos ServerError | 不支持的启动模式, y un payload vacío se acepta pero arranca con la GPU conectada (start_mode: "gpu"). Usa la consola web para el modo 无卡模式 de ¥0.1/hr mientras tanto; esta herramienta lo expondrá cuando la API lo haga.

• Verificación de identidad requerida antes de que la API responda en absoluto.

• Operaciones ausentes: renombrado, apagado programado, redimensionado, migración, restablecimiento del sistema.

• Las credenciales SSH pueden cambiar en cualquier ciclo de encendido — puerto y contraseña de root. AutoDL puede reprogramar la instancia en una máquina diferente. No siempre ocurre (se observó una parada/arranque real manteniendo ambos idénticos), que es precisamente lo que hace peligroso el almacenamiento en caché: un valor obsoleto funciona con la frecuencia suficiente para ocultar el error hasta que deja de hacerlo. Esta herramienta los vuelve a leer en cada conexión, así que nunca tienes que pensar en ello.

• running no significa que sshd esté listo. Una instancia recién creada informa de running antes de aceptar conexiones. Los intentos de conexión aquí se espacian en lugar de lanzarse uno tras otro.

• Una sesión SSH no interactiva casi no tiene PATH. Sin python, pip ni conda — viven en /root/miniconda3/bin y llegan solo a través del perfil de inicio de sesión. Cada comando remoto aquí se ejecuta bajo bash -lc por esa razón.

• La liberación requiere un apagado completado, y un segundo power_off en una instancia que ya se está deteniendo es un error. Ambos se manejan internamente.

También vale la pena saberlo: una instancia que permanece apagada durante 15 días consecutivos se libera y sus datos se borran.

Verificado contra la API en vivo el 2026-08-23: ciclo de vida completo (crear → ejecución SSH → ida y vuelta SFTP → detener → iniciar → ejecutar de nuevo → liberar) en una 4090D, coste total ¥0.10.

Las tablas de especificaciones de GPU, regiones e imágenes base están integradas porque la API no expone ningún endpoint de catálogo. Si AutoDL las cambia, por favor abre un issue.

Desarrollo

npm install
npm run build
npm test            # 325 tests, no network access, no cost
npm run lint
npm run typecheck

Las pruebas reales de extremo a extremo alquilan una GPU real y cuestan dinero real, así que son opt-in:

AUTODL_E2E=1 AUTODL_TOKEN=<token> npm run test:e2e

Siempre apagan la instancia en un afterAll, incluso en caso de fallo. Añade AUTODL_E2E_RELEASE=1 para liberarla también.

Contribuciones

Issues y PRs bienvenidos — consulta CONTRIBUTING.md. Especialmente valiosos: correcciones al catálogo estático y códigos de error reales de la API que aún no hemos mapeado (AutoDL no los documenta).

Licencia

MIT