@minato-aqukin/autodl-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Minato-Aqukin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,415 @@
+# autodl-cli
+
+> **Unofficial.** This project is not affiliated with, endorsed by, or sponsored by AutoDL.
+> "AutoDL" is used only to identify the platform this tool talks to.
+
+Manage [AutoDL](https://www.autodl.com/) GPU instances from the command line — and let
+your coding agent do it too.
+
+Built on AutoDL's **official open API**, so the developer token stays valid indefinitely
+and nothing breaks when the web console is redesigned.
+
+[简体中文](./README.zh-CN.md)
+
+---
+
+## Why
+
+When an AI agent needs a GPU box mid-task, it has no way to get one: AutoDL's instances
+are created by clicking through a web console. This gives the agent three ways in, all
+backed by the same core:
+
+| Entry point | For | How |
+|---|---|---|
+| **CLI** | humans | `autodl create --gpu 4090 --ttl 2h` |
+| **MCP server** | Claude Code, Cursor, Cline, … | `autodl mcp` over stdio |
+| **SDK** | Node programs | `import { createInstance } from "@minato-aqukin/autodl-cli"` |
+
+Every command speaks `--json` with a stable schema and a documented exit code, so an
+agent can branch on the result without parsing prose.
+
+## Install
+
+```bash
+npm install -g @minato-aqukin/autodl-cli   # then: autodl <command>
+npx @minato-aqukin/autodl-cli <command>    # or without installing
+```
+
+Requires Node.js 22+.
+
+## The dashboard
+
+```bash
+autodl tui     # or just `autodl` in an interactive terminal
+```
+
+On a machine with no token yet it opens on a login screen offering two things —
+configure a token, or quit. Paste the token, it is verified against the API before
+being saved, and you land on the dashboard. Once configured, `autodl` goes straight in.
+
+A live table of your instances: status, GPU, region, **how long each has been powered on
+and roughly what that has cost**, and how much TTL is left. Keys: `↑↓` move, `Enter`
+detail, `s` start, `x` stop, `c` copy the SSH command to the clipboard, `ctrl+d` release, `g` GPU stock,
+`n` new instance, `r` refresh, `ctrl+l` log out, `q` quit. The two that change or destroy
+something take ctrl rather than a bare key; shift makes no difference to either, and the
+hints are printed all-lowercase so they do not read as bindings you hold shift for.
+
+`ctrl+d` release wipes the instance permanently, which is why it is not a bare `d`.
+
+`ctrl+l` clears the saved token and returns to the login screen, after a confirmation — and
+it says so when `AUTODL_TOKEN` or `--token` will outrank whatever you save next. If the
+API rejects the token while the dashboard is open — expired, reset, verification lapsed —
+polling stops and the same login screen is one keystroke away, rather than leaving a
+frozen table above an endless stream of 401s.
+
+It fills the terminal and shows your account id and balance in the header. Copying with
+`c` puts only the SSH command on the clipboard — never the root password, which any
+process could then read. Where no clipboard helper exists (SSH sessions, containers) it
+falls back to OSC 52 and says so, since the terminal never confirms.
+
+It runs on the terminal's alternate screen, so it owns a fixed canvas instead of
+scrolling below whatever was already there, and quitting restores your prompt and
+scrollback untouched.
+
+It exists because AutoDL bills on power state: the expensive mistake is not a wrong
+command, it's an instance nobody remembered to stop. Leaving this open makes that visible.
+
+Two deliberate honesty constraints. A rate is only knowable from a **running** instance's
+snapshot, so a stopped instance shows elapsed time and no money — inventing a number
+would be worse than showing none. And while a rate is still loading the total says so
+rather than quietly under-reporting.
+
+The TUI never runs in a pipe, in CI, or under `--json`: it exits with code 2 and an
+explanation instead of taking over a terminal that isn't there. A bare `autodl` outside
+an interactive terminal still prints help exactly as before.
+
+## Setup
+
+The official API needs a developer token from an **identity-verified** account
+(个人或企业实名认证). Get it from the AutoDL console → 设置 → 开发者 Token.
+
+```bash
+autodl login              # verifies the token, then saves it with 0600 permissions
+autodl account            # balance, vouchers, lifetime spend
+```
+
+Token precedence: `--token` › `AUTODL_TOKEN` › `~/.config/autodl-cli/config.json`.
+
+## Quick start
+
+```bash
+# 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
+```
+
+Or do the whole thing in one verb:
+
+```bash
+autodl run "python train.py" \
+  --gpu 4090 --sync ./ --pull /root/autodl-cli/checkpoints --ttl 4h
+```
+
+That creates an instance, waits for it, uploads your code, streams the command's output,
+downloads the results, and powers the instance off — including on Ctrl-C.
+
+## Use it from an agent
+
+### Claude Code
+
+```bash
+claude mcp add autodl -- npx -y @minato-aqukin/autodl-cli mcp
+```
+
+### Cursor / Cline / any MCP client
+
+```json
+{
+  "mcpServers": {
+    "autodl": {
+      "command": "npx",
+      "args": ["-y", "@minato-aqukin/autodl-cli", "mcp"],
+      "env": { "AUTODL_TOKEN": "your-token" }
+    }
+  }
+}
+```
+
+Tools exposed: `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`. Plus an `autodl://instances` resource.
+
+MCP defaults are deliberately stricter than the CLI's, because nobody is watching:
+a 2-hour TTL is applied unless you ask for longer, releasing requires an explicit
+`confirm: true`, and passwords come back redacted unless requested.
+
+### Shell / CI
+
+```bash
+autodl ls --json | jq -r '.data[] | select(.status=="running") | .uuid'
+```
+
+## Deploying a git project
+
+```bash
+# 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` differs from `run` in one deliberate way: it **stops** the instance at the end
+instead of releasing it. A stopped instance keeps its disks, so the next deploy reuses
+the environment you already built. `--on-finish release` opts out.
+
+Code lands in `/root/autodl-tmp/<repo>` — the data disk. AutoDL's system disk is a fixed
+30GB that also gets packed into any saved image; the data disk is separate, faster and
+expandable. The trade-off worth knowing: **data-disk contents are not included when you
+save an image**, so put the environment on the system disk and the code here.
+
+Dependencies are auto-detected in this order, first hit wins — `environment.yml` →
+`requirements.txt` → `pyproject.toml` → `package-lock.json`/`package.json`. Override with
+`--setup "<cmd>"`, or skip with `--no-setup`.
+
+Remote commands run through a **login shell**. AutoDL images keep `python`, `pip` and
+`conda` in `/root/miniconda3/bin`, which only reaches `PATH` via the login profile — a
+plain non-interactive `ssh host "pip install ..."` exits 127. This applies to
+`autodl exec` too, so it behaves the way it does when you `autodl ssh` in by hand.
+
+Cloning from GitHub or HuggingFace automatically enables AutoDL's academic proxy
+(`source /etc/network_turbo`). Gitee is domestic and skips it. `--no-accel` disables it.
+AutoDL notes the proxy is "for academic use, with no stability guarantee".
+
+Private repos: `--git-token`, or `GIT_TOKEN` / `GITHUB_TOKEN` in the environment. The
+token never reaches a log line, an error message, `--json` output, or the checkout's
+stored git remote.
+
+## Checking GPU stock
+
+```bash
+autodl stock --gpu 4090        # where are the free cards
+autodl stock                   # everything, everywhere
+```
+
+**Read this table carefully — the numbers are less authoritative than they look.** They
+come from AutoDL's elastic-deployment stock endpoint, the only capacity API that exists,
+and it does not track Pro instance availability. Measured on 2026-08-23: it reported 140
+idle RTX 4090D in `westDC3` while creating a Pro instance there answered *"暂无库存"* —
+and the identical request with no region constraint succeeded, landing in `beijingDC2`.
+
+Two consequences, both baked into the tool:
+
+- **Creating an instance never narrows regions on its own.** Omitting `data_center_list`
+  gives AutoDL the widest choice, which empirically succeeds most often.
+- **Only two regions accept a Pro instance at all**: `westDC3` (西北B区) and `beijingDC2`
+  (北京B区). The other nine in the stock table are elastic-deployment only; passing one
+  to `--region` is rejected up front rather than failing later with AutoDL's opaque
+  "请求参数错误". The `可建Pro` column marks which is which.
+
+## The cost guard
+
+**AutoDL bills purely on power state.** An instance that finished training an hour ago
+costs exactly as much as one at 100% utilisation. This is the single easiest way for an
+unattended agent to waste real money, so the protection is built in rather than optional.
+
+Three layers:
+
+1. **Inside the instance.** `--ttl 2h` arms a detached `sleep && shutdown` on the box
+   itself via `start_command`. It fires even if this CLI is killed, your laptop sleeps,
+   or the network dies. This is the layer that actually protects your wallet.
+2. **A local ledger.** Every command opportunistically sweeps instances past their TTL
+   and powers them off. Catches the cases layer 1 can't — a `start_command` that
+   silently failed, or a manual power-on with no fresh timer.
+3. **Idle detection.** `autodl guard idle <id>` samples GPU utilisation over SSH and
+   shuts down after a sustained lull.
+
+```bash
+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
+```
+
+A **balance gate** also refuses to create an instance when your wallet is below
+`--min-balance` (default ¥5). AutoDL doesn't reclaim instances the moment the balance
+hits zero — it keeps them to protect your data — so a low balance turns into a stuck,
+unusable instance rather than a clean failure.
+
+## The agent contract
+
+Stable across minor versions. Breaking changes require a major.
+
+**stdout in `--json` mode is pure JSON.** Progress, prompts and warnings all go to
+stderr, so `autodl ... --json | jq` is always safe.
+
+```jsonc
+// success
+{ "ok": true, "data": { /* ... */ } }
+
+// failure
+{ "ok": false, "error": { "code": "NO_STOCK", "message": "…", "hint": "…", "requestId": "…" } }
+```
+
+| Exit | Meaning | Error codes |
+|---:|---|---|
+| 0 | Success | — |
+| 1 | Generic failure | `GENERIC`, `API_ERROR`, `NETWORK` |
+| 2 | Bad arguments | `USAGE` |
+| 3 | Token missing or invalid | `AUTH_MISSING`, `AUTH_INVALID` |
+| 4 | Resource not found | `NOT_FOUND` |
+| 5 | Out of budget / blocked by a guard | `INSUFFICIENT_BALANCE`, `GUARD_BLOCKED` |
+| 6 | No GPU stock | `NO_STOCK` |
+| 7 | Timed out | `TIMEOUT` |
+| 8 | SSH failure | `SSH_FAILED` |
+
+`autodl exec` and `autodl run` instead exit with the **remote** command's exit code, so
+`autodl exec box "make test" && deploy` behaves the way you'd expect.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `login` / `logout` / `whoami` | Token management |
+| `account` | Balance, vouchers, lifetime spend |
+| `ls [--status]` | List instances |
+| `info <id> [--show-password]` | Details, live SSH info, resource usage |
+| `create --gpu <spec>` | Create a pay-as-you-go Pro instance |
+| `start` / `stop` / `rm <id>` | Power on / off / release |
+| `ssh <id>` | Interactive login (extra flags pass through to `ssh`) |
+| `exec <id> <cmd…>` | Run a command, stream output, propagate exit code |
+| `push` / `pull <id>` | SFTP transfer, recursive, respects ignore files |
+| `run <cmd…>` | Create → sync → run → fetch → power off |
+| `deploy <repo>` | Create → clone → install deps → start → **stop, keeping data** |
+| `stock [--gpu] [--region]` | Live GPU stock per region |
+| `guard ttl\|cancel\|idle\|list\|sweep` | Cost guards |
+| `image save <id> <name>` / `images` | Private image management |
+| `gpus` / `regions` | Catalogue lookup |
+| `tui` | Interactive dashboard (also entered by a bare `autodl`) |
+| `mcp` | Run as an MCP server |
+
+Global flags: `--json`, `--yes`, `--token`, `--base-url`, `--lang zh|en`, `--verbose`,
+`--no-color`, `--no-sweep`.
+
+`push` and `pull` skip `.git`, `node_modules`, `__pycache__`, `.venv` and friends, then
+apply `.autodlignore` if present, falling back to `.gitignore`.
+
+## SDK
+
+```ts
+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);
+```
+
+Everything re-exported from the package root is public API. Prices arrive as yuan
+(`number`), timestamps as ISO strings, and Go's `sql.NullTime` shape is flattened to
+`string | null`.
+
+## What the official API cannot do
+
+These are AutoDL's limits, not this tool's. Knowing them up front saves a lot of
+confusion:
+
+- **Pay-as-you-go only.** No daily/weekly/monthly plans and no renewal endpoint.
+- **Pro instances only.** The seven specs in `autodl gpus` — the cheaper standard
+  instances aren't reachable through the open API.
+- **No usable stock query for Pro.** The one capacity endpoint reports elastic-deployment
+  stock, which demonstrably does not match Pro availability (see above). Creation is
+  effectively a blind attempt; no capacity means exit code 6 and another spec to try.
+- **Only two regions accept a Pro instance**: `westDC3` and `beijingDC2`.
+- **No CPU-only boot _yet_.** AutoDL's own wording is deliberately provisional:
+  `payload` is documented as `"gpu：有卡开机, 暂不支持API以无卡模式开机"` — *not yet*
+  supported, rather than never. Confirmed on a live instance 2026-08-24: `cpu`,
+  `no_gpu`, `nogpu`, `cpu_only`, `cpu-only` and `none` all return
+  `ServerError | 不支持的启动模式`, and an empty `payload` is accepted but boots with the
+  GPU attached (`start_mode: "gpu"`). Use the web console for the ¥0.1/hr 无卡模式 in the
+  meantime; this tool will expose it once the API does.
+- **Identity verification required** before the API will respond at all.
+- **Missing operations:** rename, scheduled shutdown, resizing, migration, system reset.
+- **SSH credentials can change on any power cycle** — port *and* root password. AutoDL
+  may reschedule the instance onto a different machine. It doesn't always happen (a real
+  stop/start was observed keeping both identical), which is precisely what makes caching
+  dangerous: a stale value works often enough to hide the bug until it doesn't. This tool
+  re-reads them on every connection, so you never have to think about it.
+- **`running` does not mean sshd is ready.** A freshly created instance reports `running`
+  before it accepts connections. Connection attempts here are spaced out rather than
+  fired back to back.
+- **A non-interactive SSH session has almost no PATH.** No python, pip or conda — they
+  live in `/root/miniconda3/bin` and arrive only through the login profile. Every remote
+  command here runs under `bash -lc` for that reason.
+- **Releasing requires a completed shutdown**, and a second `power_off` on an instance
+  that is already stopping is an error. Both are handled internally.
+
+Also worth knowing: **an instance left shut down for 15 consecutive days is released and
+its data wiped.**
+
+Verified against the live API on 2026-08-23: full lifecycle (create → SSH exec → SFTP
+round trip → stop → start → exec again → release) on a 4090D, total cost ¥0.10.
+
+The GPU spec, region and base-image tables are baked in because the API exposes no
+catalogue endpoint. If AutoDL changes them, please
+[open an issue](https://github.com/Minato-Aqukin/AutoDL-cli/issues).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test            # 325 tests, no network access, no cost
+npm run lint
+npm run typecheck
+```
+
+Real end-to-end tests rent an actual GPU and cost actual money, so they're opt-in:
+
+```bash
+AUTODL_E2E=1 AUTODL_TOKEN=<token> npm run test:e2e
+```
+
+They always power the instance down in an `afterAll`, even on failure. Add
+`AUTODL_E2E_RELEASE=1` to release it too.
+
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). Especially valuable:
+corrections to the static catalogue, and real API error codes we haven't mapped yet
+(AutoDL doesn't document them).
+
+## License
+
+[MIT](./LICENSE)