非官方项目。 本项目与 AutoDL 官方无任何关联，未获其背书或赞助。 名称中的 "AutoDL" 仅用于指代本工具所对接的平台。
用命令行管理 AutoDL GPU 实例 —— 并且让你的 AI agent 也能管。
基于 AutoDL 官方开放 API 构建：开发者 Token 长期有效，网页控制台改版也不会导致工具失效。
当 AI agent 在执行任务途中需要一台 GPU 机器时，它没有任何办法拿到 —— AutoDL 的实例只能在网页 控制台点出来。本项目提供三个入口，共用同一套核心逻辑：
| 入口 | 面向 | 用法 |
|---|---|---|
| CLI | 人 | autodl create --gpu 4090 --ttl 2h |
| MCP server | Claude Code、Cursor、Cline… | autodl mcp（stdio） |
| SDK | Node 程序 | import { createInstance } from "@minato-aqukin/autodl-cli" |
每个命令都支持 --json，输出结构稳定、退出码有明确语义，agent 无需解析自然语言就能判断结果。
npm install -g @minato-aqukin/autodl-cli # 之后直接用 autodl 命令
npx @minato-aqukin/autodl-cli <command> # 或者不安装直接用需要 Node.js 22 及以上。
autodl tui # 交互式终端里直接敲 autodl 也进还没配置 Token 的机器上，它会先进登录页，给两个选项——配置 Token 登入，或退出。
粘贴 Token 后会先向 API 验证再保存，然后直接进看板。已经配置过的，敲 autodl 直接进。
一张会自己刷新的实例表：状态、GPU、地区、已开机多久、大概花了多少钱、TTL 还剩多少。
快捷键：↑↓ 移动、Enter 详情、s 开机、x 关机、ctrl+d 释放、g 库存、
r 刷新、ctrl+l 退出登录、? 帮助、q 退出。释放和退出登录需要确认。
详情页（Enter 进入）里还有实例级操作：h 自动认证 SSH、f 文件管理、
t 传输队列、c 复制 SSH 命令、n 新建实例。
ctrl+d 释放会永久清空实例，所以它不是单个 d。
ctrl+l 会在二次确认后清除本地 Token 并回到登录页；如果本次会话的 Token 来自 AUTODL_TOKEN
或 --token，确认框会直说它的优先级高于接下来保存的 Token。看板开着时 Token 失效了
（过期、被重置、实名状态变化），刷新会立刻停下，并给出一个回登录页的入口——
而不是让你对着一张不再更新的表和刷不完的 401。
重新登录也遵守 --token › AUTODL_TOKEN › 本地 Token 的优先级。有覆盖项时，
保存另一个 Token 不会切换账号；覆盖项失效时需要修改或移除它并重启 TUI，不会悄悄
改用刚保存的账号。库存查询遇到认证失败时也会结束当前会话。
界面占满终端，头部显示账号 ID 与余额。c 只把 SSH 命令写进剪贴板，不含 root 密码
——剪贴板任何进程都能读。没有剪贴板工具的环境（SSH 会话、容器）会退回 OSC 52 并如实说明，
因为终端不会回应是否成功。
它跑在终端的备用屏上，因此拥有一块固定画布，不会接在之前的残留输出后面滚动； 退出时会完整还原你的提示符和滚动历史。
做它的理由很简单：AutoDL 按开机时长计费，最贵的错误不是敲错命令，而是"忘了还开着"。 把这张表开着，这件事就一直是可见的。
有两处刻意的诚实约束。单价只能从运行中实例的 snapshot 拿到，所以已关机的实例 只显示时长、不显示金额——编一个看起来合理的数字比留空更糟。单价还没拉到时， 汇总栏会明说"总额偏低"，而不是安静地少报。 账号续航会等所有运行实例的单价齐全后才给出时长，不会把未知单价当成免费。 终端高度不足时（包括 80×24），资源和计费面板会让位给实例列表和按键提示； 窄屏上下堆叠所占的高度也会计入判断。
TUI 不会在管道、CI 或 --json 下启动：它会以退出码 2 退出并说明原因，
而不是去接管一个并不存在的终端。非交互环境下裸 autodl 仍然和以前一样打印帮助。
先 Enter 进详情页再按 h，它会临时交出整个终端，用实时实例密码建立 SSH 会话；
退出或断线后返回看板，不是看板内嵌入终端。
也可运行 autodl ssh <id> --auto-auth。自动认证模式使用 ssh2，不读取 OpenSSH 配置；
需要 ~/.ssh/config、agent 或 -L 转发时，继续使用普通 autodl ssh <id>。
实现使用 Node.js 的跨平台终端和文件接口，无需安装 sshpass；支持 Linux、macOS 和原生 Windows。
详情页按 f 打开本地/远端双栏，窄屏显示活动侧，Tab 切换。文件操作：
| 按键 | 操作 |
|---|---|
↑↓、Enter、← |
选择、进入目录、返回父目录 |
Space / a |
多选 / 全选或清空 |
g / p |
跳转路径 / 直接输入传输来源和目标目录 |
u |
把选中项传到对侧目录，确认方向后加入队列 |
s / c |
切换单向增量同步 / 内容校验 |
m / r / x |
新建目录 / 改名或同端移动 / 确认后永久删除 |
Q / Esc |
查看队列 / 返回 |
相对路径以对应侧当前目录为基准。每个选中来源的文件名或目录名保留在目标目录下：
例如把本地 project 传到远端 /root/work，结果是 /root/work/project。
文件管理器传输明确选中的目录内容，不套用旧 push 命令的忽略规则；
符号链接及特殊文件跳过，队列详情按 v 可逐项查看全部跳过记录。
普通传输遇到同名文件会暂停询问：o 覆盖、s 跳过、b 保留两份，
a 切换对本任务其余冲突应用同一选择。同步则以所选方向的来源为准：
跳过未变化文件，整份替换变化文件，不删除目标端独有文件。
默认比较大小和修改时间；可开启 SHA-256 内容校验，但需要读取两端文件内容，
远端校验会通过 SFTP 读取数据，因此严格校验可能消耗与下载相当的带宽。
队列按顺序执行，显示字节进度、速度和状态。可返回看板继续操作；
在队列按 Enter 看详情、c 取消、r 恢复已暂停或已取消任务。
网络中断有界重试；实例关机或认证失败会暂停，不自动开机。
文件页打开后只建立一条浏览连接，切目录、建目录、改名、删除都复用它；
目录内容每次实时读取，连接断了下次操作自动重连，离开文件页即释放。
CLI 的 files 和 queue 命令与看板共用同一队列记录：
queue add 进去的任务能在看板 t 里确认冲突和恢复，反之亦然。
queue resume、queue resolve 和 queue add --wait 会在前台执行任务，未完成时以非零退出码结束。
未完成文件写入目标目录里的 .autodl-*.part，完成后才替换目标，取消不会截断原文件。
续传会验证来源版本及已传前缀；来源变化或临时文件损坏时重新传输。
覆盖远端文件需要服务器的 OpenSSH 原子重命名扩展；不支持时保留原文件并报错。
任务记录位于配置目录的 transfers/，按账号和 API 地址隔离，不保存凭证。
退出/退出登录会暂停任务；下次进入队列后手动恢复，退出后不后台传输。
同一账号队列只允许一个进程写入，崩溃遗留的所有权记录可自动回收。
取消会保留续传文件；确定不再恢复时可删除对应任务的 .part 和本地续传记录。
官方 API 需要已完成实名认证（个人或企业）账号的开发者 Token。 获取路径：AutoDL 控制台 → 设置 → 开发者 Token。
autodl login # 先验证 Token 有效，再以 0600 权限落盘
autodl account # 查看余额、代金券、累计消费Token 优先级：--token › AUTODL_TOKEN 环境变量 › ~/.config/autodl-cli/config.json。
# 租一台两小时后自动关机的卡，并等它就绪
autodl create --gpu 4090 --ttl 2h --wait
# 开始干活
autodl ls
autodl ssh pro-76419909953e # 交互式登录
autodl exec pro-76419909953e "nvidia-smi" # 单次执行，透传远程退出码
autodl push pro-76419909953e ./src /root/work # SFTP 上传
autodl pull pro-76419909953e /root/work/out . # SFTP 下载
# 停止计费
autodl stop pro-76419909953e
autodl rm pro-76419909953e --yes # 不可逆：数据将被永久清空也可以用一条命令跑完全流程：
autodl run "python train.py" \
--gpu 4090 --sync ./ --pull /root/autodl-cli/checkpoints --ttl 4h它会自动建实例 → 等就绪 → 上传代码 → 流式输出执行过程 → 回传产物 → 关机。 按 Ctrl-C 中断时同样会走完关机流程。
claude mcp add autodl -- npx -y @minato-aqukin/autodl-cli mcp{
"mcpServers": {
"autodl": {
"command": "npx",
"args": ["-y", "@minato-aqukin/autodl-cli", "mcp"],
"env": { "AUTODL_TOKEN": "你的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，密码默认脱敏返回。
autodl ls --json | jq -r '.data[] | select(.status=="running") | .uuid'# 开一台卡，拉代码、自动装依赖、跑起来，然后关机
autodl deploy owner/repo --gpu 4090 --start "python train.py" --ttl 4h
# 长驻服务：后台启动并保持实例运行
autodl deploy owner/repo --gpu 4090 --start "python app.py" --detach
# 过几天回来：同一台机器开机 + git pull，环境不用重建
autodl deploy owner/repo --instance pro-76419909953e --start "python train.py"deploy 和 run 只有一个刻意的区别：结束时关机而不释放。关机的实例磁盘完整保留，
下次部署直接复用已经装好的环境。想释放用 --on-finish release。
代码放在 /root/autodl-tmp/<仓库名>，也就是数据盘。AutoDL 的系统盘固定 30G 且会被打包进
保存的镜像；数据盘独立、更快、可扩容。有个值得知道的取舍：数据盘的内容保存镜像时不包含，
所以环境装系统盘、代码放数据盘才是对的组合。
依赖按这个顺序自动探测，先命中先用：environment.yml → requirements.txt →
pyproject.toml → package-lock.json/package.json。--setup "<命令>" 可完全覆盖，
--no-setup 跳过。
远程命令一律走登录 shell。AutoDL 镜像把 python、pip、conda 放在
/root/miniconda3/bin，这个路径只有登录时的 profile 才会加进 PATH——直接
ssh host "pip install ..." 会以退出码 127 失败。autodl exec 同样如此，
因此它的行为和你手动 autodl ssh 进去敲命令一致。
从 GitHub / HuggingFace 拉代码时会自动开启学术资源加速（source /etc/network_turbo）。
Gitee 是境内的，不需要也不会开。--no-accel 可关闭。官方注明该加速「仅供学术用途、不保证稳定」。
私有仓库用 --git-token，或设置环境变量：GIT_TOKEN 适用于任意主机，GITHUB_TOKEN 只用于
github.com，GITEE_TOKEN 只用于 gitee.com，GitHub 的 Token 不会被发给其他主机。凭证不会出现在
日志、错误信息、--json 输出里，也不会留在实例内 git remote 的配置中。
autodl stock --gpu 4090 # 哪里有空闲卡
autodl stock # 全部地区全部型号这张表要谨慎看——数字没有它看上去那么权威。 它来自 AutoDL 的「弹性部署 GPU 库存」接口，
这是唯一存在的容量接口，但它不反映 Pro 实例的可用量。2026-08-23 实测：接口显示
westDC3 有 140 张空闲 RTX 4090D，而在该地区创建 Pro 实例返回*「暂无库存」*；同样的请求
不带地区限制反而成功了，最终落在 beijingDC2。
由此得出两个结论，都已经写进工具的行为里：
- 创建实例时不会自作主张缩小地区范围。 不传
data_center_list让 AutoDL 自行调度， 实测成功率最高。 - 只有两个地区能创建 Pro 实例：
westDC3（西北B区）和beijingDC2（北京B区）。 库存表里另外 9 个地区只用于弹性部署，写进--region会被提前拒绝，而不是等到 AutoDL 回一句含糊的「请求参数错误」。表里的可建Pro列标明了这个区别。
AutoDL 只按开机时长计费，与是否使用 GPU 无关。 一台一小时前就跑完训练的实例， 和一台满载运行的实例，花的钱一模一样。这是无人值守的 agent 最容易烧钱的地方， 所以护栏是内建的，而不是可选项。
三道防线：
- 实例内定时器。
--ttl 2h会通过start_command在机器内部埋一个后台sleep && shutdown。即使 CLI 被杀、笔记本合盖、网络断掉，它照样会触发。 真正保住钱包的是这一层。 - 本地台账。 每次执行任何命令时顺手扫一遍，发现超过 TTL 仍在运行的实例就关掉。
用于兜住第一道防线覆盖不到的情况 —— 比如
start_command静默失败， 或者实例被手动开机但没有重新设置定时器。 - 闲置检测。
autodl guard idle <id>通过 SSH 采样 GPU 利用率，持续闲置后自动关机。
autodl guard ttl pro-xxx 2h # 给运行中的实例设置/重设定时关机
autodl guard cancel pro-xxx # 取消（同时清除本机台账；无法确认实例内定时器已停止时退出码为 1）
autodl guard list # 查看本机台账
autodl guard sweep # 立即清理所有超时实例
autodl guard idle pro-xxx --threshold 5 --samples 6 --interval 1m另外还有余额闸门：账号可用余额低于 --min-balance（默认 ¥5）时直接拒绝创建实例。
因为 AutoDL 在余额归零时并不会立刻回收实例（平台优先保数据），
余额不足的结果往往不是干净地失败，而是留下一台卡住、用不了的实例。
在次版本之间保持稳定，破坏性变更走主版本。
--json 模式下 stdout 是纯 JSON。 进度、提示、警告一律走 stderr，
所以 autodl ... --json | jq 永远安全。
未知命令、未知选项和缺少参数统一返回退出码 2、USAGE 错误；启用 --json 时
也会输出一个 JSON 错误对象。tui --json 同样遵守错误输出契约；显式请求帮助或
版本号仍输出原来的文本。
| 退出码 | 含义 | 对应 error code |
|---|---|---|
| 0 | 成功 | — |
| 1 | 通用错误 | GENERIC、API_ERROR、NETWORK |
| 2 | 参数错误 | USAGE |
| 3 | Token 缺失或无效 | AUTH_MISSING、AUTH_INVALID |
| 4 | 资源不存在 | NOT_FOUND |
| 5 | 余额不足 / 被护栏拦截 | INSUFFICIENT_BALANCE、GUARD_BLOCKED |
| 6 | GPU 无库存 | NO_STOCK |
| 7 | 超时 | TIMEOUT |
| 8 | SSH 失败 | SSH_FAILED |
autodl exec 和 autodl run 例外：它们透传远程命令的退出码，
这样 autodl exec box "make test" && deploy 才符合直觉。唯一的例外是 run/deploy
结束后未能关机或释放实例：此时退出码为 1，并在 data.cleanup.error 中说明，因为这台实例可能仍在计费。
| 命令 | 说明 |
|---|---|
login / logout / whoami |
Token 管理 |
account |
余额、代金券、累计消费 |
ls [--status] |
列出实例 |
info <id> [--show-password] |
详情、实时 SSH 信息、资源占用 |
create --gpu <spec> |
创建按量计费 Pro 实例 |
start / stop / rm <id> |
开机 / 关机 / 释放 |
ssh <id> [--auto-auth] |
系统 SSH 登录，或使用实例密码自动认证；系统模式支持额外 OpenSSH 参数 |
exec <id> <cmd…> |
远程执行，流式输出，透传退出码 |
files ls/mkdir/mv/rm <id> |
实例文件浏览与管理（SFTP，连接复用） |
queue add/ls/resume/cancel/resolve |
串行传输队列，与看板共用同一队列 |
run <cmd…> |
建实例 → 同步 → 执行 → 回传 → 关机 |
deploy <仓库> |
建实例 → 拉代码 → 装依赖 → 启动 → 关机保留数据 |
stock [--gpu] [--region] |
各地区 GPU 实时库存 |
guard ttl|cancel|idle|list|sweep |
成本护栏 |
image save <id> <name> / images |
私有镜像管理 |
gpus / regions |
查询内置目录 |
tui |
交互式看板（裸 autodl 也进入） |
mcp |
以 MCP server 运行 |
全局参数：--json、--yes、--token、--base-url、--lang zh|en、--verbose、
--no-color、--no-sweep。
push / pull 默认跳过 .git、node_modules、__pycache__、.venv 等目录，
然后应用 .autodlignore；没有该文件时回退到 .gitignore。
import {
AutoDLClient,
createInstance,
execCommand,
powerOffInstance,
waitForRunning,
} from "@minato-aqukin/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。
以下是 AutoDL 的限制，不是本工具的限制。提前知道能少走很多弯路：
- 只支持按量计费。 没有包日/包周/包月，也没有续费接口。
- 只能创建 Pro 实例。 即
autodl gpus里那七个规格 —— 更便宜的标准实例 官方开放 API 租不到。 - 没有可用于 Pro 的库存查询接口。 唯一的容量接口返回的是弹性部署库存，实测与 Pro 可用量 对不上（见上文）。创建实际上仍是盲试，无货时返回退出码 6，只能换规格重试。
- 只有两个地区能创建 Pro 实例：
westDC3和beijingDC2。 - 暂不支持无卡模式开机。 官方对
payload的原文是 「gpu：有卡开机, 暂不支持API以无卡模式开机」——是暂不，不是永不。 2026-08-24 实测确认：cpu、no_gpu、nogpu、cpu_only、cpu-only、none一律返回ServerError | 不支持的启动模式；传空payload会被接受， 但开出来仍然带卡（start_mode: "gpu"）。在官方开放之前，¥0.1/时 的无卡模式 只能用网页控制台；等 API 支持了，这个工具会跟进。 - 必须先完成实名认证，否则 API 根本不响应。
- 缺失的操作： 改名、定时关机、升降配置、迁移实例、重置系统。
- 开关机后 SSH 端口和 root 密码可能变化。 因为实例可能被调度到另一台机器。 但并不是每次都变（实测一次 stop/start 后端口和密码完全没变），这恰恰是缓存最危险的地方： 旧值能用的次数足够多，多到足以把 bug 藏起来。本工具每次连接都重新拉取，所以你不用操心。
- 状态变成
running不代表 sshd 已经就绪。 新建实例会在还不能接受连接时就报running， 所以本工具的连接重试之间是有退避间隔的，而不是连着打。 - 非交互 SSH 会话几乎没有 PATH。 没有 python、没有 pip、没有 conda——它们在
/root/miniconda3/bin，只有登录 profile 会加进来。所以这里所有远程命令都走bash -lc。 - 释放必须等关机真正完成，而且对已经在关机中的实例再调一次关机会报错。两者都已在内部处理。
另外值得注意：实例连续关机 15 天会被平台释放，数据全部清空。
已于 2026-08-23 对真实 API 做过完整验证：4090D 上跑通 创建 → SSH 执行 → SFTP 双向传输 → 关机 → 开机 → 再次执行 → 释放，总花费 ¥0.10。
GPU 规格、地区、公共基础镜像三张表是内置的静态数据，因为官方 API 没有目录接口。 如果 AutoDL 更新了，欢迎来 提 issue。
npm install
npm run build
npm test # 325 个测试，不访问网络，不产生任何费用
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 官方并未公开这些错误码）。
发布的 npm 包把 Ink、React 及其依赖打包进了 dist/，它们的许可证声明随包附在
dist/THIRD_PARTY_LICENSES.txt。