Private beta.
The CLI is being rolled out to beta accounts. Keys are created in the console and access is enabled per account — ask for it and we will tell you where the queue stands. This page is the interface as it is being shipped, so you can see whether it fits your workflow before asking.
Install#
$ curl -fsSL https://cli.spotgpus.com/install.sh | sh $ spot version spot 0.4.0 (beta)
A single static binary, no runtime to install. Windows users can run it under WSL. The installer never needs root: it drops the binary in ~/.local/bin.
Authenticate#
Create a key in the console under API keys, then:
$ spot auth login --key sg_live_xxxxxxxxxxxxxxxx Signed in as you@example.com · balance $128.40 # Or keep it out of the config file entirely: $ export SPOT_API_KEY=sg_live_xxxxxxxxxxxxxxxx
The key is stored in ~/.config/spotgpus/config.toml with mode 0600. SPOT_API_KEY takes precedence, which is what CI should use.
spot launch#
$ spot launch --gpu h100-sxm --count 1 --tier spot \ --region us-east --template pytorch --volume train-data --relaunch Instance i-7f3a2c H100 ×1 us-east spot @ $0.55/h ssh root@i-7f3a2c.spotgpus.com ✓ reachable in 41s
| Flag | Default | What it does |
|---|---|---|
--gpu <slug> | required | A model from spot gpus, for example h100-sxm |
--count <n> | 1 | GPUs in the node; must be a size the model offers |
--tier spot|ondemand | spot | Whether the instance may be reclaimed |
--region <code> | first with capacity | us-east, us-west, eu-central |
--template <slug> | pytorch | A template, or --image ghcr.io/you/img:tag for your own |
--volume <name|ref> | none | Attach a persistent volume at /mnt/vol |
--disk <gb> | none | Create a volume of that size and attach it |
--relaunch | off | Queue for the next free capacity after a reclaim |
--name <text> | none | A label for your own reference, 60 characters |
--json | off | Print the instance object instead of a table |
--wait | on | Block until the instance is reachable; --no-wait returns immediately |
spot ls, spot show#
$ spot ls REF GPU TIER REGION STATE UPTIME COST i-7f3a2c H100 ×1 spot us-east running 02:14 $1.23i-9b10e4 RTX 4090 spot eu-central stopped — $0.13 $ spot show i-7f3a2c --json | jq .volume { "ref": "vol-4b19c7", "mount": "/mnt/vol", "size_gb": 500 }
spot watch#
Follows an instance and runs a command when a reclaim notice arrives — the CLI equivalent of polling the metadata endpoint from inside the machine.
$ spot watch i-7f3a2c --on-notice ./drain.sh --on-stop ./notify.sh 18:04:12 running $0.23 so far 18:12:40 notice reclaim in 02:00 → ./drain.sh 18:14:40 stopped volume vol-4b19c7 kept, address kept 18:18:50 relaunched i-9b10e4 spot @ $0.55/h
spot stop, spot rm#
$ spot stop i-7f3a2c # stops billing, keeps disk, IP and configuration $ spot start i-7f3a2c # same instance, next free capacity of that model $ spot rm i-7f3a2c # terminate; the volume survives until you delete it
spot volume#
$ spot volume create train-data --size 500 --region us-east vol-4b19c7 500 GB us-east $40.00/month $ spot volume ls REF NAME SIZE REGION ATTACHED vol-4b19c7 train-data 500 GB us-east i-7f3a2c $ spot volume rm vol-4b19c7 # must be detached; deletion is final
spot gpus#
$ spot gpus --min-vram 80 --tier spot SLUG NAME VRAM SPOT ONDEMAND AVAILABLE b200-sxm B200 SXM 180 GB $1.69 $2.49 16 h200-sxm H200 SXM 141 GB $0.75 $1.09 32 h200-nvl H200 NVL 141 GB $0.69 $0.99 16 h100-sxm H100 SXM 80 GB $0.55 $0.89 96
Scripting notes#
- Exit codes.
0success,1usage or validation error,2no capacity for that model and region,3insufficient balance,4authentication failure. --jsoneverywhere. Every command accepts it and prints one object or one array. Combine withjqrather than parsing tables.- Idempotence.
spot launch --idempotency-key <uuid>returns the same instance if the call is retried, which matters when a CI step reruns after a network error. - No hidden state. The CLI keeps nothing but the key: two machines with the same key see exactly the same objects.