Runpodctl

Runpodctl

Manage GPU pods, serverless endpoints, templates, volumes, and models.

Install

curl -sSL https://cli.runpod.net | bash (Linux/macOS, and Windows via WSL) or brew install runpod/runpodctl/runpodctl. Manual binaries and the Windows and conda steps live in the runpodctl README, beside the install.sh they describe. The command surface comes from the binary — runpodctl <resource> <action> --help — or the generated pages under `runpodctl/docs/`.

Old runpodctl 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. So, before any work: - Update to the latest build — check runpodctl version, then run runpodctl update (or reinstall from the latest release). - Pin to one recent version for the whole task. - Never switch between an old and a new binary mid-task (that flip-flop is a known failure). - Verify once — runpodctl version shows the current build before you continue.

Quick start

runpodctl update                    # FIRST: get on the latest build — old versions cause confusing errors
runpodctl version                   # confirm the current version before doing any work
export RUNPOD_API_KEY=your_key      # Non-interactive auth (agents) — runpodctl reads this
runpodctl doctor                    # Interactive first-time setup (API key + SSH) — for humans
runpodctl --help                    # See current top-level commands
runpodctl pod create --help         # Inspect exact current flags before creating
runpodctl gpu list                  # See available GPU types
runpodctl datacenter list           # GPU availability per data center (use to 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-v21 --gpu-id "NVIDIA GeForce RTX 4090"  # Create from template
runpodctl pod list                  # List your pods

Auth: an agent should export RUNPOD_API_KEY=... (non-interactive). runpodctl doctor is interactive (prompts) and also sets up SSH keys — good for a human's first run, not for scripted use.

API key: https://console.runpod.io/user/settings

Live Help Is Authoritative

Live runpodctl --help output is authoritative for exact flags, aliases, and command syntax. Use this skill for workflows, decision rules, safety notes, and common examples.

runpodctl --help
runpodctl <resource> --help
runpodctl <resource> <action> --help

Before using unfamiliar commands, inspect live help first. Do not rely on this skill as an exhaustive flag reference.

*What live help does not cover: output shapes, error codes, and exit-code behavior. `--help` lists flags; it never shows you what a failure looks like. For those, use [reference/output-and-errors.md](reference/output-and-errors.md) — and when in doubt, probe the binary*: run the command wrong on purpose (runpodctl serverless get nope) and read the JSON it emits. 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; anything else silently returns JSON). A failure from the resource commands is a single 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. status is there only when the failure arrived on a non-2xx response — GraphQL reports a missing resource as HTTP 200 + null data, so if status == 404 misses every GraphQL not-found.

runpodctl never retries internally; nothing backs off for you.

• `not_found` always means the API lacks the resource, never a mistyped local path (that's cli_error).
• `cli_error` is a mixed bucket: local environment problems and invocation mistakes the command validates itself (e.g. ssh remove-key with neither --name nor --fingerprint). Only cobra-enforced required flags are usage_error.
• `usage_error` = unknown command/flag, bad args, missing cobra-required flag; usage text follows the JSON. Runtime errors no longer print usage.
• Non-empty stderr does not mean failure — deprecation warning: and note: lines go to stderr on success too. Gate on the exit code, then parse stderr.

Coded errors, the serverless urls object and GPU pricing all need runpodctl ≥ v2.8.0. Older binaries emit {"error":"…"} with no `code` and no `status` — still JSON-shaped, so a switch (err.code) silently gets undefined rather than failing loudly. Gate on `code` being present, not on JSON-vs-plaintext; runpodctl version is unreliable for this (plaintext, and a source build reports a placeholder version).

Full code table, the surfaces that still print plaintext (exec, legacy pod commands, project), and the env-var table (incl. RUNPOD_INVOKE_URL): [reference/output-and-errors.md](reference/output-and-errors.md).

Decision Rules

• Use Hub when the user wants a known deployable app or worker such as vLLM, ComfyUI, Whisper, or a Runpod-maintained repo.
• Picking a worker: prefer a first-party or well-adopted, recently-released worker on a broad, high-availability GPU pool. Observable signals via 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.
• "Active worker" = minimum workers, not maximum. If a user asks for an "active worker," they mean --workers-min 1 (keep one worker always warm → no cold start), not --workers-max 1 (that only caps the ceiling). A warm min-1 worker is ideal for development/iteration.
• ⚠️ A min-1 worker bills continuously, even while idle (it defeats scale-to-zero). When you set --workers-min 1 for dev, you must set it back to --workers-min 0 (or delete the endpoint) when done — otherwise it quietly runs up cost.
• Needs runpodctl ≥ v2.10.0. On earlier binaries --workers-min 0 and --idle-timeout 0 were silently dropped from the update request (omitempty ate the zero), so the reset looked like it applied and the endpoint kept billing. Check runpodctl version; on an older binary confirm with serverless get <id> and fall back to PATCH https://rest.runpod.io/v1/endpoints/<id> with an explicit {"workersMin":0}.
• serverless update has no `--gpu-id` flag. To change an existing endpoint's GPU pool, call PATCH https://rest.runpod.io/v1/endpoints/<id> with {"gpuTypeIds":[...]} directly.