runpod/runpod-plugins-official/runpodctl

Runpodctl

Manage GPU pods, serverless endpoints, templates, volumes, and models. For serverless development workflows, use the Runpod SDK regardless of CLI version.

Install

curl -fsSL https://cli.runpod.net | sudo bash (Linux/macOS, and Windows via WSL) or brew install runpod/runpodctl/runpodctl. Manual binaries and the Windows and conda steps: the runpodctl README, beside the install.sh they describe. API key: https://console.runpod.io/user/settings

Old builds silently lack newer flags/behaviors (e.g. --model-reference doesn't exist before

v2.4.0) and produce confusing downstream errors, and the Homebrew tap can lag well behind.

Before any work: update to the latest build (runpodctl version, then runpodctl update,

or reinstall from the latest release); **pin one

recent version for the whole task; never switch between an old and a new binary mid-task**

(a known failure); verify once with runpodctl version before you continue.

Quick start

runpodctl update && runpodctl version   # FIRST: latest build, confirmed, before any work
export RUNPOD_API_KEY=your_key      # agents: non-interactive auth, read by runpodctl
runpodctl doctor                    # humans: interactive first-time setup (prompts for API key + SSH keys); not for scripted use
runpodctl pod create --help         # inspect exact current flags before creating
runpodctl gpu list                  # GPU types
runpodctl datacenter list           # GPU availability per data center (co-locate GPU + volume)
runpodctl hub search vllm           # find a hub repo
runpodctl serverless create --hub-id <id> --name "my-vllm"  # deploy from hub
runpodctl template search pytorch   # find a template
runpodctl pod create --template-id runpod-torch-v280 --gpu-id "NVIDIA GeForce RTX 4090" --min-cuda-version 12.8  # create from template
runpodctl pod list                  # your pods

Live Help Is Authoritative

Live runpodctl --help, runpodctl <resource> --help and runpodctl <resource> <action> --help are authoritative for exact flags, aliases, and syntax (the generated pages under `runpodctl/docs/` mirror them). Inspect live help before unfamiliar commands; this skill covers workflows, decision rules, safety notes, and common examples, and is not an exhaustive flag reference.

Live help does not cover output shapes, error codes, or exit-code behavior: use reference/output-and-errors.md, and when in doubt probe the binary (run it wrong on purpose, e.g. runpodctl serverless get nope, and read the JSON). Every doc is a snapshot, this skill included; the binary in front of you wins.

Output & errors

Data is JSON on stdout (--output=yaml is the only alternative; there is no table format; v2.10.0+ rejects any other value with usage_error, v2.9.0 and earlier silently return JSON). A failure is one flat JSON object on stderr plus a non-zero exit:

{"error":"failed to get endpoint: endpoint not found","code":"not_found","status":404}

• Branch on `code`, never on `status` or the message (GraphQL reports a missing resource as HTTP 200 + null data, so status is often absent).
• Retry with backoff only on `network_error`, `rate_limited`, `server_error`; the API commands never retry internally. no_credentials = no key set (for network-volume upload/download: no S3 API keys, or no API key for the data-center lookup, which --data-center-id skips; the message names which); unauthorized/forbidden = a key is set but wrong or lacks access (don't re-prompt). usage_error, cli_error, bad_request, not_found, conflict: fix the input. Any other code is fatal: surface error verbatim.
• `network-volume upload`/`download` (v3.1.0+) retry on their own (429, 5xx, dropped connections). transfer_incomplete = it stopped partway: rerun the same command, it resumes. volume_full = grow the volume (network-volume update --size), then rerun.
• Gate on the exit code, then parse stderr: deprecation warning:/note: lines go to stderr on success too.
• Coded errors, the serverless `urls` object and GPU pricing need runpodctl ≥ v2.8.0. Older binaries emit {"error":"…"} with no code, so gate on code being present, not on runpodctl version.
• `project` behaves differently per build (exit 0 with errors on stdout through v3.0.1; exit 1 with a Runpod SDK notice in builds with runpod/runpodctl#382). Treat that notice as fatal.

Full code table, cli_error vs usage_error, plain-text exceptions, the exact SDK notice, and the env-var table (incl. RUNPOD_INVOKE_URL): [reference/output-and-errors.md](reference/output-and-errors.md).

Decision Rules

• Hub for a known deployable app or worker (vLLM, ComfyUI, Whisper, a Runpod-maintained repo). Picking a worker: prefer a first-party or well-adopted, recently-released worker on a broad, high-availability GPU pool; signals in runpodctl hub list: --owner runpod-workers (first-party), --order-by releasedAt/updatedAt (recency), --order-by deploys/stars (adoption). Don't pin a scarce large-GPU tier a small model doesn't need.
• Templates when the user already has a template ID, wants reusable image/config defaults, or needs lower-level control than Hub. `pod create --image` for a specific Docker image with no saved template.
• Serverless for request/response inference APIs and scalable workers; pods for interactive work, notebooks, training, debugging, or long-lived sessions. CPU pods for preprocessing, file movement, lightweight scripts, and non-CUDA work; GPU pods when CUDA, model inference, training, or GPU memory is required.
• "Active worker" = minimum workers, not maximum: --workers-min 1 (one worker always warm → no cold start; ideal for development/iteration), not --workers-max 1 (that only caps the ceiling).
• ⚠️ A min-1 worker bills continuously, even while idle (it defeats scale-to-zero). After dev you must set --workers-min 0 (or delete the endpoint), or it quietly runs up cost.
• Needs runpodctl ≥ v2.10.0. Earlier binaries silently dropped --workers-min 0 and --idle-timeout 0 from the update request (omitempty ate the zero): the reset looked applied and the endpoint kept billing. Check runpodctl version; on an older binary confirm with serverless get <id> and fall back to PATCH https://api.runpod.io/v2/serverless/<id> with an explicit {"workers":{"min":0}}.
• Set the execution timeout on every endpoint create. A v2 create without timeout comes back "timeout": 0 (live-verified 2026-10-29; why it matters). runpodctl ≥ 2.14.0 has serverless create --execution-timeout <seconds> (as of 2.14.0 serverless update does not; check --help); read the timeout back with serverless get, and fix a 0 with PATCH https://api.runpod.io/v2/serverless/<id> {"timeout":<ms>}.
• serverless update has no `--gpu-id` flag. To change an endpoint's GPU pools, PATCH https://api.runpod.io/v2/serverless/<id> with {"gpu":{"pools":["ADA_24"]}} (pool ids, from the pool field of GET /v2/catalog/gpus). Sending pools without excludedTypes clears any exclusions.
• CPU serverless endpoints: runpodctl serverless create --compute-type CPU (on REST v2, send cpu instead of gpu). Never send "computeType":"CPU" to REST v1 POST https://rest.runpod.io/v1/endpoints: it silently provisions a GPU endpoint (evidence).
• Leave `--cloud-type` at its `SECURE` default (why). Pass --cloud-type COMMUNITY only when the user explicitly asks (a public port 22 there needs a machine with a public IP, which the CLI cannot request).
• A CPU pod gets 2 vCPUs on whichever CPU flavor has the most stock; --name defaults to the image name without its tag. CPU pods take a network volume (--network-volume-id) but not a pod volume (--volume-in-gb is rejected). Do not pass GPU flags.
• Set a CUDA floor on every GPU create: `--min-cuda-version 12.8` (pod create and serverless create; not template create). Without it a modern image can land on a host too old to run it, and the create will not reject it: the container dies at startup or silently runs on CPU. 13.0 only for a CUDA-13 image; omit for CPU. Rule, exceptions and capacity check: `runpod-usage` gpu-selection "pin the CUDA floor".
• Waiting for a resource to be usable: use `--wait`, don't hand-roll a poll loop (v2.9.0+). create returns once the resource is scheduled, which is why a "RUNNING" pod often refuses ssh and a fresh endpoint 404s. pod create --wait returns when port 22 answers with an ssh banner. pod create --wait-for running (v2.15.0+) returns when the container is up, no ssh needed: use it when container-up is all the task needs, or for an image that does not start sshd (most cpu images, since cpu pods get no Runpod-managed ssh), where plain --wait would bill through the whole timeout and then fail; a cpu image that starts its own sshd still satisfies plain --wait, so keep that when the user needs ssh. serverless create --wait returns when /health reports a ready or running worker. On timeout or ctrl-c the resource is kept and its id is in the error object's id field: read it and clean up, don't assume nothing was created (a pod bills by the second; an endpoint with no running worker doesn't, but starts one on the first request).
• A service on a pod (Ollama, ComfyUI, a dev server): declare its --ports and --env at creation when possible (runpodctl pod update can change them on an existing pod), then follow the pod development loop in runpod-usage (reference/pod-workflows.md): SSH-exec the install, bind to 0.0.0.0, poll the proxy URL until it answers.
• SSH: connection details from runpodctl pod get <pod-id> or runpodctl ssh info <pod-id>. runpodctl has no interactive-shell command: ssh info returns the connection command + key but does not connect, so run ssh user@host "command" yourself.
• Network volumes are location-sensitive: pick the data center from the GPU stock read (datacenter list, or gpu list --include-unavailable) before creating the volume, and create it once. If pod create is then refused for stock, re-read stock: retry once with the same volume when its data center shows stock; otherwise ask the user (wait, another GPU type there, the console's Deploy when available, or a move to another data center, which is the user's call). Never delete the volume to try another data center; on a move, name it in the hand-back (id, data center, storage cost) and delete it only when the user asks. Move data onto or off a volume with network-volume upload / download (v3.1.0+, resumable); send / receive for machine to machine.
• Clean up paid resources after tests: serverless endpoints, pods, and temporary volumes created for validation.
• Cost guard: remove the pod when the work is done (runpodctl pod remove <pod-id>); a stopped pod still bills for disk and any volume. Unattended deadline: pod-workflows (schedule a stop from inside the pod).
• `--stop-after` / `--terminate-after` never worked. Before v2.12.0 pod create accepts both, but the backend never enforced them, so the pod keeps running and billing past the deadline; v2.12.0 removed them. If `runpodctl pod create --he