CLI Reference

Every command accepts --profile NAME to target a specific profile. Run substratecloud <command> --help for the authoritative flag list.

config — credentials & profiles

Command	Description
config init [--profile N] [--config PATH] [--force]	Create/replace a credential profile (interactive).
config use <profile>	Switch the active profile.
config ls	List profiles.
config show [profile]	Show a profile's settings (token redacted).

See Authentication & Config for details.

inventory — browse GPU capacity

Command	Description
inventory ls [--gpu H100] [--location REGION] [--gpu-count N] [--max-price P]	List matching configurations, cheapest first.
inventory cheapest [--gpu A100] [--region R] [--min-count N] [--max-price P]	Print the single cheapest match.

substratecloud inventory ls --gpu h100 --max-price 3
substratecloud inventory cheapest --gpu a100

instance — lifecycle

Command	Description
instance ls [--tag SUBSTR]	List active instances.
instance get <id-or-name>	Show one instance (status, IP, SSH command, cost).
instance launch --name N [--gpu] [--region] [--max-price] [--ssh-key] [--os] [--tag ...] [--workload FILE] [--wait/--no-wait] [--timeout S] [--yes]	Launch an instance. Prints estimated daily/weekly spend and asks to confirm before billing starts.
instance terminate [<id-or-name>] [--all-tagged TAG] [--yes]	Terminate one or many instances. Irreversible — stops billing.

substratecloud instance launch --gpu a100 --name exp-1
substratecloud instance ls
substratecloud instance get exp-1
substratecloud instance terminate exp-1

note

--ssh-key accepts a registered key name or a UUID. Instance names are not unique; if two active instances share a name you must pass an explicit UUID.

run — one-shot workload launch

Launch a workload from a file and block until the instance is active:

substratecloud run ./workload.yaml --gpu h100 --name exp-1 --timeout 900

plan / apply / destroy — manifest workflow

Command	Description
plan <manifest.yaml> [--no-safety-net]	Dry-run. Never calls the launch API.
apply <manifest.yaml> [--force] [--no-safety-net]	Idempotent launch; reuses an existing matching instance. --force destroys a drifted instance and relaunches.
destroy <name-or-path> [--all]	Tear down instance(s) launched by apply.

substratecloud plan    minimal-docker.yaml
substratecloud apply   minimal-docker.yaml
substratecloud destroy minimal-docker

See SDK Usage → Declarative manifests for the manifest format.

workload — inspect specs without launching

Command	Description
workload validate <file>	Parse and validate a Docker workload YAML/JSON. Does not contact the API.
workload render --from <boot-script.yaml> [-o out.sh]	Render a boot script to bash. (Boot-script YAML is under active design; render via Python for now.)

check / show-gpus / cost — operational helpers

Command	Description
check	Validate that the configured token + base URL work.
show-gpus [--max-price P]	Cheapest available listing per GPU family.
cost [--tag ...]	Client-side spend report (uptime × cost_per_hour).

substratecloud check
substratecloud show-gpus
substratecloud cost --tag team:platform