CLI Reference
Commands that take a deployment id (status, exec, logs, ssh, terminate, resubmit) accept it as an optional argument. Omit the id in an interactive terminal to pick from recent deployments; in CI or when piped, set ANYCLOUD_DEPLOYMENT_ID or pass the id explicitly.
anycloud submit
Deploy a container image. Alias: anycloud run.
anycloud submit <image> [-- command...] [options]
Use -- before the command if it contains flags, to separate them from submit options.
| Option | Description |
|---|---|
-i, --id <id> | Custom deployment ID |
-e, --env <KEY=VALUE> | Environment variable (repeatable). Use -e KEY to read from current shell. Likely-sensitive keys trigger a warning |
--env-file <file> | Load env vars from .env file |
--secret <name> | Named secret to inject as env vars (repeatable). See Secrets |
-p, --persist | Keep VM alive after job completes |
--persist-bucket | Keep the spot checkpoint bucket after the job completes (spot only). Independent of --persist — see Spot Instances |
--gpus <gpus> | GPU access (all or count) |
--shm-size <size> | Shared memory size (e.g., 8g) |
--memory <limit> | Memory limit (e.g., 32g) |
--cpus <count> | CPU limit |
--runtime <runtime> | Container runtime (e.g., nvidia) |
--ipc <mode> | IPC mode (host, private, shareable) |
--ulimit <ulimit> | Ulimit settings (repeatable) |
--gpu-type <type> | GPU type (e.g., h100, a100:8). Repeatable for an ordered fallback pool. See CloudConfig Internals |
--vm-type <type> | VM instance type (e.g., g6e.xlarge). Repeatable for an ordered fallback pool. See CloudConfig Internals |
--credentials <name> | Optional pinned compute credentials. Omit to let anycloud choose from saved named credentials |
--region <region> | Pin compute to one cloud region. Escape hatch for quota tests, debugging, or explicit user constraints; leave unset for normal jobs |
--spot | Use spot/preemptible instances |
--disk-size <gb> | Root disk capacity in GB |
--disk-tier <tier> | AWS root disk performance tier: medium (default), high, or ultra |
--zone <zone> | Availability zone |
--input-bucket <name> | Input bucket for read-only data |
--output-bucket <name> | Output bucket for results |
--input-storage-credentials <name> | Credentials for input bucket (cross-cloud) |
--input-storage-region <region> | Region for input bucket storage |
--output-storage-credentials <name> | Credentials for output bucket (cross-cloud) |
--output-storage-region <region> | Region for output bucket storage |
--checkpoint-storage-credentials <name> | Credentials for the spot checkpoint bucket (cross-cloud) |
--checkpoint-storage-region <region> | Region for spot checkpoint bucket storage |
<image> is required. Pass inline cloud flags such as --credentials <name> plus --vm-type <type> or --gpu-type <type>. Leave --region unset for normal jobs; pinning a region disables region failover.
--disk-size controls root disk capacity; --disk-tier controls AWS gp3 root disk performance. For example, --disk-size 100 --disk-tier high uses a 100 GB root disk with the high tier.
Every deployment boots from a provider base VM and pulls the requested Docker image. Image digest resolution still ensures that mutable tags resolve to the correct container content.
anycloud serve
Deploy a long-running HTTP server.
anycloud serve <image> [-- command...] [options]
anycloud serve upgrade <id> <image> [-- command...]
serve supports the same cloud, environment, secret, and Docker runtime options
as submit, except for job-only flags such as --persist, --persist-bucket,
--spot, and bucket mounts.
Server containers must listen on $PORT; the public endpoint is
https://<id>.anycloud.sh.
anycloud images
Browse container images in GitHub Container Registry (GHCR). Alias: imgs.
anycloud images [options]
| Option | Description |
|---|---|
-f, --filter <text> | Filter by image, owner, package, or tag |
--owner <owner> | Only packages owned by this GitHub user or org |
--list | List packages and tags instead of the interactive picker |
--no-tags | List packages only; skip per-package tag lookups |
--json | Emit images as compact JSON |
--only-refs | Emit full image refs (ghcr.io/owner/image:tag), one per line |
In a TTY, run anycloud images with no options for an interactive picker that
prints the selected ghcr.io/owner/image:tag. Use --list for a table, or
--json / --only-refs for scripts — both emit only machine output to stdout
(progress and warnings go to stderr). --only-refs requires tags, so it cannot
be combined with --no-tags.
anycloud status
View detailed status of a deployment.
anycloud status [id]
anycloud status <id> --watch
anycloud status <id> --json | jq '.vms[0].ip'
anycloud status <id> --watch --json | jq -c '.deployment.state'
| Option | Description |
|---|---|
--verbose | Show detailed logs |
-w, --watch | Poll and redraw status until the deployment reaches a terminal state |
--interval <seconds> | Polling interval for --watch (default 5, minimum 1) |
-p, --period <window> | Limit the picker to deployments started within a window (e.g. 7d, 24h) |
-n, --limit <count> | Max deployments in the picker, newest first (default 200, max 1000) |
--json | Emit raw deployment status JSON to stdout |
Omit the id in a TTY for an interactive picker; non-TTY/CI requires an
explicit id or ANYCLOUD_DEPLOYMENT_ID. --json requires an explicit id
too — picker chrome would otherwise corrupt the JSON pipe.
With --json, the payload mirrors the API's status response shape — an
object with deployment, vms[], and events[]. Human chrome is
routed to stderr, so anycloud status <id> --json 2>/dev/null is a clean
pipe for jq and scripts. The schema is considered stable across patch
releases.
With --watch --json, stdout is newline-delimited JSON: one compact
StatusResponse object per poll until the deployment reaches a terminal state.
anycloud list
List all deployments. Alias: anycloud ls.
anycloud list [options]
anycloud list --json | jq '.[].id'
| Option | Description |
|---|---|
-f, --filter <text> | Filter by id, image, cloud, region, state, session, or agent (substring) |
--status <state> | Only deployments with this state (exact, e.g. running, failed) |
--credential <name> | Only deployments using this named credential |
--session <id> | Match a session: id, prefix, label, or agent:hash |
--agent <name> | Only deployments from this agent (claude, codex, cursor, …) |
-p, --period <window> | Only deployments started within a window (e.g. 7d, 24h, 30d) |
-n, --limit <count> | Max deployments to show, newest first (default 200, max 1000) |
--json | Emit deployments as a compact JSON array |
--csv | Emit deployments as CSV (header + one row per deployment) |
--only-ids | Emit just deployment IDs, one per line |
In a TTY, bare anycloud list opens a summary view picker so you can choose
persisted jobs, one state, or all jobs before the table renders. Passing any
filter/scope flag or machine-readable output flag skips the picker and prints
directly.
When invoked non-interactively by an agent, output is scoped to that
agent's own session; pass --session/--agent to target another.
Interactive (TTY) runs are never scoped. See
Agents.
With --json, emits an array of deployment objects — the same shape the
API returns. An empty result is [] (exit 0), never a "No deployments
found" message.
anycloud exec
Execute a command in the job's Anycloud-controlled execution environment.
anycloud exec "nvidia-smi"
anycloud exec job-abc123 "python train.py"
On VM-host providers this runs inside the workload Docker container. On
provider-run-image providers this runs over Anycloud's SSH transport in the
provider-controlled execution environment. Use anycloud status for durable
lifecycle, error, and status information.
anycloud logs
View workload container stdout/stderr logs for VM-host deployments.
anycloud logs job-abc123
anycloud logs job-abc123 --follow
| Option | Description |
|---|---|
-f, --follow | Stream log output until interrupted |
-w, --watch | Alias for --follow |
Provider-run-image deployments such as Vast do not expose container logs through
this command yet. If your job writes logs to a file, use
anycloud exec <id> "tail -f <path>".
anycloud ssh
Open an interactive shell for a VM-host deployment.
anycloud ssh job-abc123
anycloud ssh server-abc123
anycloud ssh job-abc123 --vm
anycloud ssh job-abc123 --snapshot
By default, opens a shell inside the workload container. --vm opens a host VM
diagnostic shell. --snapshot commits an exited workload container and opens a
shell in the snapshot. SSH shell access is not supported for provider-run-image
providers yet; use anycloud exec <id> "<command>" there.
anycloud terminate
Terminate one or more deployments and clean up cloud resources.
anycloud terminate [ids...]
anycloud resubmit
Resubmit one or more deployments in a terminal state. Resets the deployment back to the queue for re-provisioning with the same configuration.
anycloud resubmit [ids...]
anycloud cost
View estimated compute costs for your deployments.
anycloud cost [id]
| Option | Description |
|---|---|
-p, --period <period> | Time period: 7d, 30d, 90d (default: 30d) |
--session <id> | Match a session: id, prefix, label, or agent:hash |
--agent <name> | Only deployments from this agent (claude, codex, cursor, …) |
--json | Emit cost report as compact JSON |
Without an ID, shows costs for all deployments in the selected period.
Like list, agent invocations are scoped to their own session; pass
--session/--agent to look at another.
anycloud throttle
Set a burn-rate cap — the maximum $/hr across running VMs at any instant. When the live burn rate would exceed the cap, new submits wait in queued and auto-dispatch as running VMs end; running jobs are never killed. See Spend Controls.
anycloud throttle set [usd] [--agent-session] # e.g. set 20 for $20/hr
anycloud throttle show
anycloud throttle unset [--agent-session]
| Option | Description |
|---|---|
--agent-session | Apply the cap per agent session instead of account-wide (set / unset) |
anycloud budget
Set a calendar-window spend cap (day, week, or month). When exceeded, new submits wait in queued until the window resets or the cap is raised; running jobs are never killed. See Spend Controls.
anycloud budget set [usd] --per <day|week|month> [--agent-session]
anycloud budget show
anycloud budget unset --per <day|week|month> [--agent-session]
| Option | Description |
|---|---|
--per <period> | Window: day, week, or month (required for set / unset) |
--agent-session | Apply the cap per agent session instead of account-wide |
anycloud spend
Show throttle and budget headroom across all caps in one view.
anycloud spend show [--json]
| Option | Description |
|---|---|
--json | Emit JSON (adds percentUsed / headroomUsd; drops bars/color) |
anycloud db query
Run a read-only SQL query against the local API database. Useful for ad-hoc inspection of deployment state from a script or agent, when no dedicated subcommand exposes the field you need.
anycloud db query "<sql>" [--json]
| Option | Description |
|---|---|
--json | Emit { rows, rowCount, truncated } JSON |
Only SELECT, WITH, EXPLAIN, and PRAGMA statements are accepted; writes are refused at the SQLite engine level. Results are capped at 10 000 rows and the response sets truncated: true when the cap fires.
Examples:
anycloud db query "SELECT id, state FROM deployments ORDER BY started_at DESC LIMIT 10"
anycloud db query "SELECT * FROM deployment_events WHERE deployment_id = 'abc'" --json
anycloud db schema
List the local API database's tables, columns, foreign keys, and indexes. The --json form is the shape an agent should use for introspection before running anycloud db query.
anycloud db schema [table] [--json]
| Option | Description |
|---|---|
--json | Emit schema as JSON |
With no argument, lists every user table and view. With a table name, narrows to that one.
Examples:
anycloud db schema
anycloud db schema deployments --json
anycloud docs
Print the published anycloud docs to stdout. A thin wrapper over https://anycloud.sh/llms.txt (index) and https://anycloud.sh/llms-full.txt (full corpus), so agents can ingest product context in one call.
anycloud docs [--all] [--url]
| Option | Description |
|---|---|
--all | Print the full markdown corpus instead of the index |
--url | Print the docs URL instead of fetching |
Examples:
anycloud docs # short index — titles + descriptions
anycloud docs --all # full markdown corpus
anycloud docs --url # print the URL only
anycloud regions
List available regions for a cloud. With --vm-type, narrows to regions that offer that VM type, sorted cheapest first.
anycloud regions [cloud] [--vm-type <type>] [--spot] [--json]
Omitting cloud opens a picker in an interactive terminal. In non-interactive mode, pass a cloud explicitly, for example aws, gcp, azure, lambda, or vast. --json never opens prompts.
| Option | Description |
|---|---|
--vm-type <type> | Only regions offering this VM type, sorted cheapest first |
--spot | Use spot pricing for the --vm-type sort |
--json | Emit regions as a JSON array |
Examples:
anycloud regions
anycloud regions aws
anycloud regions aws --vm-type p5.48xlarge --spot
anycloud vm-types
List VM types available in a region.
anycloud vm-types [cloud] [region] [--accelerator <gpu>] [--json]
Omitting cloud or region opens pickers in an interactive terminal. In non-interactive mode, pass both explicitly. Clouds are aws, gcp, azure, lambda, and vast. --json never opens prompts.
| Option | Description |
|---|---|
--accelerator <gpu> | Only VM types with this accelerator (e.g. H100) |
--json | Emit VM types as a JSON array |
anycloud gpus
List available GPUs and prices for a cloud. With --type, filters to one GPU SKU and prints a priced offerings table (GPU, count, VM type, on-demand and spot $/hr). In non-interactive mode, omit the cloud and pass --type to compare the cheapest match for a GPU across all clouds.
anycloud gpus [cloud] [--type <gpu>] [--json]
anycloud gpus --type <gpu> [--count <n>] [--spot] [--json] # cross-cloud comparison
Bare anycloud gpus opens a picker in an interactive terminal: choose one cloud or compare all clouds, then pick a GPU type for the cross-cloud comparison. In non-interactive mode, pass a cloud or --type explicitly. --json never opens prompts.
| Option | Description |
|---|---|
--type <gpu> | Filter to a specific GPU SKU (e.g. H100). Required when the cloud is omitted non-interactively |
--count <n> | Cross-cloud comparison only: filter to a specific GPU count (e.g. 8) |
--spot | Cross-cloud comparison only: sort by spot price (falls back to on-demand where spot is missing) |
--json | Emit results as a JSON array |
Examples:
anycloud gpus
anycloud gpus aws
anycloud gpus gcp --type H100
anycloud gpus --type H100 --count 8 --spot
anycloud pricing
Look up on-demand or spot pricing for a VM type, either across all regions (cheapest first) or for one specific region.
anycloud pricing [cloud] [vm-type] [--region <r>] [--spot] [--json]
Omitting cloud or vm-type opens pickers in an interactive terminal. In non-interactive mode, pass both explicitly. Clouds are aws, gcp, azure, lambda, and vast. --json never opens prompts.
| Option | Description |
|---|---|
--region <r> | Limit pricing to one region |
--spot | Show spot prices instead of on-demand |
--json | Emit pricing as a JSON object |
anycloud bucket
Create, delete, upload, and download cloud buckets using a credential registered with anycloud credentials new. These commands go through the local API server, so the same routes back the Python SDK's Bucket.upload() / Bucket.download().
anycloud bucket create <bucket-name> --credentials <name> [--region <r>]
anycloud bucket delete <bucket-name> --credentials <name> [--region <r>]
anycloud bucket exists <bucket-name> --credentials <name> [--region <r>]
anycloud bucket upload <bucket-name> <local-path> <remote-path> --credentials <name> [--region <r>]
anycloud bucket download <bucket-name> <remote-path> <local-path> --credentials <name> [--region <r>]
anycloud bucket rm <bucket-name> <remote-path> --credentials <name> [--region <r>]
| Option | Description |
|---|---|
--credentials <name> | (required) Named cloud credential to use for the bucket command |
--region <r> | Bucket region — required for some providers/cross-region setups |
create is idempotent: if the bucket already exists and the credential can access it, the command succeeds. delete is also idempotent and removes the bucket and all of its contents; use it with care. exists sets its exit code for scripting — 0 if the bucket exists, 1 if not, 2 if the check failed. rm deletes a single object (<remote-path>) from a bucket, as opposed to delete, which removes the whole bucket.
For upload, <local-path> must be a file and <remote-path> is the object key inside the bucket. For download, parent directories for <local-path> are created automatically.
Examples:
anycloud bucket create training-data --credentials prod-aws --region us-east-1
anycloud bucket upload training-data ./data.bin datasets/data.bin --credentials prod-aws --region us-east-1
anycloud bucket download training-data datasets/data.bin ./downloads/data.bin --credentials prod-aws --region us-east-1
anycloud bucket delete training-data --credentials prod-aws --region us-east-1
anycloud credentials
Manage cloud provider credentials. Alias: anycloud creds.
anycloud credentials new # Add credentials
anycloud credentials list # List credentials
anycloud credentials list --json # Machine-readable: [{name, cloudProvider}]
anycloud credentials edit [name] # Edit credentials
anycloud credentials delete <name> # Delete credentials
| Option | Description |
|---|---|
-f, --force | Skip confirmation (for delete) |
--json | list only: emit [{name, cloudProvider}]; never leaks secrets |
anycloud secrets
Manage named secrets. Values are encrypted at rest, never returned by the
API, and injected into containers at run time when referenced via
--secret <name> (or secrets=[...] in the SDK). See the
Secrets guide.
anycloud secrets new <name> KEY=VALUE [KEY=VALUE ...] # Create or update a bundle
anycloud secrets list # List names and timestamps (no values)
anycloud secrets delete <name> [--force] # Delete a bundle
| Option | Description |
|---|---|
-f, --force | Delete even if non-terminal deployments reference the secret (returns 409 without) |
anycloud notifications
Configure a daily digest of anycloud usage (Slack today). See Notifications.
anycloud notifications enable slack [--webhook <url>] # prompts if --webhook omitted
anycloud notifications status
anycloud notifications test [channel] # defaults to slack
anycloud notifications disable [channel] # omit channel to disable all
| Option | Description |
|---|---|
--webhook <url> | Slack incoming-webhook URL (for enable) |
enable validates the webhook and posts a one-shot test message before saving, so a bad URL fails immediately.
anycloud api
Manage the active anycloud API server. By default the CLI uses
http://localhost:8080; anycloud api use persists a hosted API URL in
~/.anycloud/api-url. API_URL remains available as a one-command override.
anycloud api serve [options] # Deploy a hosted API server
anycloud api list [--json] # List local and hosted API servers
anycloud api use [target] # Set active API URL, deployment ID, or local
anycloud api info # Show active API URL, source, and health
anycloud api start [options] # Start the local API server
anycloud api start --enable-local-docker
anycloud api stop # Stop the local API server
anycloud api status # Show local API server status
anycloud api logs [-f] # View local API server logs
| Option | Description |
|---|---|
--use | Persist a newly created hosted API as the active API (serve) |
--json | Emit API target data as JSON (list) |
--port <port> | Port for local API server (default: 8080) |
--enable-local-docker | Enable anycloud submit --local jobs (start) |
--version <version> | API image version to start (default: this CLI's version) |
-f, --follow | Stream logs in real time (for logs subcommand) |
anycloud api list is read-only: it shows local and hosted API servers with
health, version, source, and the current active target. anycloud api use with
no target opens an interactive picker of healthy compatible API servers.
anycloud api use local saves http://localhost:8080 as an explicit local
target.
api start binds the API port to 127.0.0.1 only. --enable-local-docker
mounts the host Docker socket into the API container, which grants the API
host-root-equivalent Docker control; use it only when you need --local jobs.
anycloud login
Authenticate with GitHub via OAuth. Required for pulling private images from GHCR. When Docker is installed, this also logs your local Docker CLI into ghcr.io so you can push images.
anycloud login
anycloud update
Update anycloud CLI and local API image. Installer-script installs are updated
from get.anycloud.sh; Homebrew-managed installs are updated through Homebrew.
If a local API server is running, the command restarts stale API containers on
the image that matches the installed CLI.
anycloud update
anycloud quota request
📊 Start a tracked cloud-provider quota increase operation for a VM type or GPU family. When --region is omitted, anycloud uses common-region defaults for the selected cloud and VM type.
anycloud quota request # interactive: pick credential, GPU type(s), quota type(s), region
anycloud quota request <vmType> [--region <region>] [options]
anycloud quota request --gpu <name> [--credential <name>] [--region <region>] [options]
| Option | Description |
|---|---|
<vmType> | VM type (e.g. g6e.48xlarge, Standard_NC40ads_H100_v5) |
--gpu <name> | GPU family (e.g. H100, A100) — expanded to a VM type for the cloud |
--region <name> | Region to request quota in. Omit to use common-region defaults for the selected cloud and VM type |
--credential <name> | Named credential to use. The cloud is taken from this credential (or inferred from <vmType>) |
--spot | Request spot/preemptible quota instead of on-demand |
--dry-run | Print what would be submitted without calling the cloud |
--json | Emit JSON (auto-enabled when stdout is not a TTY) |
The command stores an operation locally and returns quickly while provider submissions continue in the API background worker. The command opens at most one case per region per invocation. Re-running it for a region that already has an open case returns SKIPPED together with the existing case's URL — no duplicate cases are created.
Run with no vmType and no --gpu in a TTY to get an interactive picker — anycloud prompts for a credential, then opens a searchable multi-select list of GPU instance types from the catalog. No GPU instance types are selected by default; press Space to select one or more, then Enter to confirm. The picker then asks for one quota type (on-demand or spot/preemptible), then regions; when current quota can be read, region choices show the current matching quota next to each option. Selecting multiple instance types files a request for each selected VM type, quota type, and region combination. Passing --spot skips the quota-type prompt and requests spot only; passing --region skips the region prompt. Non-TTY / --json invocations still require an explicit vmType or --gpu.
Heads up: AWS opt-in. When you fan out across regions, anycloud submits an EnableRegion call for each AWS region that is currently disabled-by-default (e.g. me-central-1, ap-east-1, af-south-1). Opt-in is asynchronous and takes a few minutes; the quota request for that region is deferred until opt-in completes. The entry's status is SUBMITTED with optInAction: enabling and a message explaining the deferral. Pass --region to scope the command to one region if you'd rather not opt anything new in.
Example (interactive output):
Quota operation quota-1781120000000-ab12cd34
Status running
Cloud AWS
Targets 0/3
Quota submissions continue in the background. Track progress with: anycloud quota operation quota-1781120000000-ab12cd34
Example (--json or piped):
{
"entries": [],
"operation": {
"id": "quota-1781120000000-ab12cd34",
"cloud": "AWS",
"dryRun": false,
"status": "queued",
"totalTargets": 3,
"completedTargets": 0,
"failedTargets": 0,
"createdAt": 1781120000000,
"updatedAt": 1781120000000
}
}
anycloud quota operation
📊 Show local progress for a tracked quota operation.
anycloud quota operation <id> [--json]
Example:
Quota operation quota-1781120000000-ab12cd34
Status completed
Cloud AWS
Targets 3/3
1. completed · g6e.48xlarge (on-demand, us-east-1) · 1 result
G and VT: ✅ 32→384 · Quota increase request submitted for review
anycloud quota status
📊 List quota requests and current quota limits. Defaults to every region in the cloud's catalog when --region is omitted (per-region calls run in parallel). In an interactive terminal, prompts for on-demand vs spot/preemptible unless --spot, --on-demand, or --json is passed. On AWS the command pulls the last 30 days of Service Quotas history, detects partial grants by comparing the current limit against the originally requested value, and reads current EC2 quota limits. On Azure it lists pending Quota-API requests, open quota-related support tickets, and current GPU-family / aggregate / public-IP limits.
anycloud quota status [--credential <name>] [--region <region>] [--spot | --on-demand] [options]
| Option | Description |
|---|---|
--credential <name> | Named credential to use. The cloud is taken from this credential (prompted if omitted in a TTY) |
--region <name> | Region to query. Omit to query every region in the catalog |
--spot | Only show spot/preemptible quota |
--on-demand | Only show on-demand quota |
--json | Emit JSON (auto-enabled when stdout is not a TTY) |
Example (partial grant on AWS):
⚠️ 1 partial · 1 region
SPOT
REGION G/VT GPUs
us-east-1 3072/4000
Example (no requests, current nonzero limits):
No quota requests · Current nonzero quota limits · 2 regions
SPOT
REGION P GPUs G/VT GPUs
us-east-1 96 4
us-west-2 96 —