autodl-cli

非官方。 本项目与 AutoDL 无关联，未获其认可或赞助。 "AutoDL" 仅用于标识本工具所对接的平台。

从命令行管理 AutoDL GPU 实例——也可以让你的编程代理来做这件事。

基于 AutoDL 的官方开放 API 构建，因此开发者令牌永久有效，即使网页控制台改版也不会出问题。

简体中文

为什么

当 AI 代理在任务中途需要一台 GPU 机器时，它没有任何办法获取：AutoDL 的实例只能通过网页控制台点击创建。本工具为代理提供了三种接入方式，全部由同一核心驱动：

每个命令都支持 --json 输出，具有稳定的模式和文档化的退出码，代理无需解析文本即可根据结果进行分支判断。

Related MCP server: lab-ops

安装

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

需要 Node.js 22 或更高版本。

仪表盘

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

在尚未配置令牌的机器上，它会先显示登录界面，提供两个选项——配置令牌或退出。粘贴令牌后，保存前会先通过 API 验证，验证通过后进入仪表盘。配置完成后，直接运行 autodl 即可进入。

实时显示实例列表：状态、GPU、区域、每台实例已开机时长及大致费用，以及剩余 TTL。按键：↑↓ 移动，Enter 查看详情，s 开机，x 关机，c 将 SSH 命令复制到剪贴板，Ctrl+D 释放，g GPU 库存，n 新建实例，r 刷新，q 退出。释放操作放在 Ctrl+D 而非单个按键上，因为它会永久删除实例。

界面占满整个终端，顶部显示账户 ID 和余额。按 c 复制时只将 SSH 命令放入剪贴板——绝不包含 root 密码，因为任何进程都可能读取到。在没有剪贴板辅助工具的环境（SSH 会话、容器）中，它会回退到 OSC 52 并明确提示，因为终端不会给出确认。

它运行在终端的备用屏幕上，拥有固定的画布而不会在已有内容下方滚动，退出时原样恢复你的提示符和回滚缓冲区。

它存在的原因是 AutoDL 按开机状态计费：最昂贵的错误不是输错命令，而是忘记关掉的实例。保持这个界面打开就能让这一点一目了然。

两个刻意的诚实约束。费率只能从运行中实例的快照得知，因此已停止的实例只显示已用时间而不显示费用——编造一个数字比不显示更糟糕。费率仍在加载时，总额会明确显示"加载中"，而不是悄悄少报。

TUI 绝不在管道、CI 或 --json 模式下运行：它会以退出码 2 退出并给出说明，而不是接管一个不存在的终端。在非交互终端中直接运行 autodl 仍会像以前一样打印帮助信息。

配置

官方 API 需要来自实名认证账户的开发者令牌（个人或企业实名认证）。在 AutoDL 控制台 → 设置 → 开发者 Token 中获取。

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

令牌优先级：--token › AUTODL_TOKEN › ~/.config/autodl-cli/config.json。

快速开始

# 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

或者用一个命令完成全部操作：

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

该命令会创建实例、等待就绪、上传代码、流式输出命令结果、下载结果文件，然后关闭实例——包括在按 Ctrl-C 时也会执行关闭。

从代理中使用

Claude Code

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

Cursor / Cline / 任何 MCP 客户端

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

暴露的工具：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。另外还有一个 autodl://instances 资源。

MCP 的默认设置刻意比 CLI 更严格，因为没有人盯着：除非你明确要求更长时间，否则默认应用 2 小时 TTL；释放实例需要显式传入 confirm: true；密码默认脱敏返回，除非明确请求。

Shell / CI

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

部署 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 与 run 有一个刻意的区别：它在结束时停止实例而不是释放。已停止的实例保留磁盘，因此下次部署可以复用你已构建的环境。--on-finish release 可退出此行为。

代码存放在 /root/autodl-tmp/<repo>——即数据盘。AutoDL 的系统盘固定为 30GB，且会打包进保存的镜像中；数据盘是独立的，更快且可扩容。值得了解的权衡：保存镜像时不包含数据盘内容，因此请将环境放在系统盘，代码放在这里。

依赖按以下顺序自动检测，先命中者优先——environment.yml → requirements.txt → pyproject.toml → package-lock.json/package.json。可用 --setup "<cmd>" 覆盖，或用 --no-setup 跳过。

远程命令通过登录 shell 运行。AutoDL 镜像将 python、pip 和 conda 放在 /root/miniconda3/bin，只有通过登录配置文件才能进入 PATH——普通的非交互式 ssh host "pip install ..." 会以 127 退出。这也适用于 autodl exec，因此它的行为与手动 autodl ssh 登录一致。

从 GitHub 或 HuggingFace 克隆时自动启用 AutoDL 的学术加速代理（source /etc/network_turbo）。Gitee 是国内平台，会跳过此步骤。--no-accel 可禁用。AutoDL 注明该代理"仅限学术用途，不保证稳定性"。

私有仓库：使用 --git-token，或环境变量 GIT_TOKEN / GITHUB_TOKEN。令牌绝不会出现在日志行、错误消息、--json 输出或检出后存储的 git remote 中。

查看 GPU 库存

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

请仔细阅读此表——这些数字并不像看起来那么权威。 它们来自 AutoDL 的弹性部署库存接口，这是唯一存在的容量 API，且不跟踪 Pro 实例的可用性。2026-08-23 实测：该接口报告 westDC3 有 140 台空闲 RTX 4090D，但在该区域创建 Pro 实例却返回*"暂无库存"*——而同样的请求不加区域限制则成功，落到了 beijingDC2。

两个后果都已内置到工具中：

• 创建实例时绝不自行限定区域。 省略 data_center_list 可让 AutoDL 有最广泛的选择，经验表明这样成功率最高。

• 只有两个区域支持 Pro 实例：westDC3（西北B区）和 beijingDC2（北京B区）。库存表中的其他九个区域仅支持弹性部署；将其中一个传给 --region 会提前被拒绝，而不是稍后以 AutoDL 晦涩的"请求参数错误"失败。可建Pro 列标明了哪些区域支持。

费用防护

AutoDL 纯粹按开机状态计费。 一小时前就完成训练的实例与 100% 利用率的实例费用完全相同。这是无人值守代理浪费真金白银的最简单途径，因此防护是内置的而非可选的。

三层防护：

1. 实例内部。 --ttl 2h 通过 start_command 在机器上设置一个分离的 sleep && shutdown 定时关机。即使本 CLI 被终止、你的笔记本电脑休眠或网络中断，它也会触发。这是真正保护你钱包的一层。

2. 本地台账。 每个命令都会顺带扫描超过 TTL 的实例并将其关机。弥补第 1 层无法覆盖的情况——start_command 静默失败，或手动开机但没有新的定时器。

3. 空闲检测。 autodl guard idle <id> 通过 SSH 采样 GPU 利用率，在持续空闲后自动关机。

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

余额门槛还会在余额低于 --min-balance（默认 ¥5）时拒绝创建实例。AutoDL 不会在余额归零的瞬间回收实例——它会保留实例以保护你的数据——因此余额不足会导致实例卡住无法使用，而不是干净利落地失败。

代理契约

在次要版本间保持稳定。破坏性变更需要主版本号变更。

--json 模式下 stdout 是纯 JSON。 进度、提示和警告都输出到 stderr，因此 autodl ... --json | jq 始终安全。

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

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

autodl exec 和 autodl run 则改为以远程命令的退出码退出，因此 autodl exec box "make test" && deploy 的行为符合你的预期。

命令

全局标志：--json、--yes、--token、--base-url、--lang zh|en、--verbose、--no-color、--no-sweep。

push 和 pull 会跳过 .git、node_modules、__pycache__、.venv 等目录，然后应用 .autodlignore（如果存在），否则回退到 .gitignore。

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);

从包根目录重新导出的所有内容都是公共 API。价格以元（number）为单位，时间戳为 ISO 字符串，Go 的 sql.NullTime 形状被扁平化为 string | null。

官方 API 无法做到的事

这些是 AutoDL 的限制，不是本工具的限制。提前了解它们可以避免很多困惑：

• 仅按量付费。 没有日/周/月套餐，也没有续费端点。

• 仅限 Pro 实例。 autodl gpus 中的七种规格——更便宜的 Standard 实例无法通过开放 API 访问。

• Pro 没有可用的库存查询。 唯一的容量端点报告的是弹性部署库存，这显然与 Pro 的可用性不匹配（见上文）。创建实际上是一次盲试；没有容量意味着退出码 6，需要再试另一种规格。

• 只有两个区域接受 Pro 实例：westDC3 和 beijingDC2。

• 尚不支持纯 CPU 启动。 AutoDL 自己的措辞是刻意留有余地的：payload 被记录为 "gpu：有卡开机, 暂不支持API以无卡模式开机" —— 尚未支持，而不是永远不支持。2026-08-24 在真实实例上确认：cpu、no_gpu、nogpu、cpu_only、cpu-only 和 none 都返回 ServerError | 不支持的启动模式，空 payload 会被接受，但会带着 GPU 启动（start_mode: "gpu"）。在此期间请使用 Web 控制台使用 ¥0.1/小时 的无卡模式；一旦 API 支持，本工具就会开放它。

• 需要身份验证，否则 API 根本不会响应。

• 缺失的操作： 重命名、定时关机、调整规格、迁移、系统重置。

• SSH 凭据可能在每次电源循环时改变——端口和 root 密码。AutoDL 可能将实例重新调度到不同的机器上。这并不总是发生（观察到一次真实的停止/启动保持了二者不变），这正是缓存危险的原因：过期的值在足够多的情况下仍然有效，足以掩盖问题，直到它不再有效。本工具在每次连接时都会重新读取它们，所以你永远不需要考虑这个问题。

• running 并不意味着 sshd 已就绪。 新创建的实例在接受连接之前就报告 running。这里的连接尝试是有间隔的，而不是连续触发。

• 非交互式 SSH 会话几乎没有 PATH。 没有 python、pip 或 conda——它们位于 /root/miniconda3/bin，只有通过登录配置文件才会加载。因此，这里的所有远程命令都在 bash -lc 下运行。

• 释放需要先完成关机，对已经处于停止过程中的实例再次执行 power_off 会报错。这两者都在内部处理。

另外值得了解：连续关机 15 天的实例会被释放，其数据会被清除。

2026-08-23 在真实 API 上验证：在 4090D 上完成完整生命周期（创建 → SSH 执行 → SFTP 往返 → 停止 → 启动 → 再次执行 → 释放），总费用 ¥0.10。

GPU 规格、区域和基础镜像表是内置的，因为 API 没有提供目录端点。如果 AutoDL 更改了它们，请提交 issue。

开发

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

真正的端到端测试会租用真实的 GPU 并花费真金白银，因此它们是可选加入的：

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

它们总是在 afterAll 中关闭实例电源，即使在失败时也是如此。添加 AUTODL_E2E_RELEASE=1 也会释放它。

贡献

欢迎提交 Issue 和 PR——请参阅 CONTRIBUTING.md。特别有价值的是：对静态目录的修正，以及我们尚未映射的真实 API 错误码（AutoDL 没有记录它们）。

许可证

MIT