Skip to main content

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.

OptionDescription
-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, --persistKeep VM alive after job completes
--persist-bucketKeep 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
--spotUse 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]
OptionDescription
-f, --filter <text>Filter by image, owner, package, or tag
--owner <owner>Only packages owned by this GitHub user or org
--listList packages and tags instead of the interactive picker
--no-tagsList packages only; skip per-package tag lookups
--jsonEmit images as compact JSON
--only-refsEmit 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'
OptionDescription
--verboseShow detailed logs
-w, --watchPoll 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)
--jsonEmit 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'
OptionDescription
-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)
--jsonEmit deployments as a compact JSON array
--csvEmit deployments as CSV (header + one row per deployment)
--only-idsEmit 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
OptionDescription
-f, --followStream log output until interrupted
-w, --watchAlias 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]
OptionDescription
-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, …)
--jsonEmit 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]
OptionDescription
--agent-sessionApply 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]
OptionDescription
--per <period>Window: day, week, or month (required for set / unset)
--agent-sessionApply 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]
OptionDescription
--jsonEmit 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]
OptionDescription
--jsonEmit { 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]
OptionDescription
--jsonEmit 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]
OptionDescription
--allPrint the full markdown corpus instead of the index
--urlPrint 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.

OptionDescription
--vm-type <type>Only regions offering this VM type, sorted cheapest first
--spotUse spot pricing for the --vm-type sort
--jsonEmit 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.

OptionDescription
--accelerator <gpu>Only VM types with this accelerator (e.g. H100)
--jsonEmit 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.

OptionDescription
--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)
--spotCross-cloud comparison only: sort by spot price (falls back to on-demand where spot is missing)
--jsonEmit 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.

OptionDescription
--region <r>Limit pricing to one region
--spotShow spot prices instead of on-demand
--jsonEmit 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>]
OptionDescription
--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
OptionDescription
-f, --forceSkip confirmation (for delete)
--jsonlist 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
OptionDescription
-f, --forceDelete 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
OptionDescription
--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
OptionDescription
--usePersist a newly created hosted API as the active API (serve)
--jsonEmit API target data as JSON (list)
--port <port>Port for local API server (default: 8080)
--enable-local-dockerEnable anycloud submit --local jobs (start)
--version <version>API image version to start (default: this CLI's version)
-f, --followStream 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]
OptionDescription
<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>)
--spotRequest spot/preemptible quota instead of on-demand
--dry-runPrint what would be submitted without calling the cloud
--jsonEmit 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]
OptionDescription
--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
--spotOnly show spot/preemptible quota
--on-demandOnly show on-demand quota
--jsonEmit 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 —