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

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.

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 — 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:

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.

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.
• CPU serverless endpoints: always create them with runpodctl serverless create --compute-type CPU — not the MCP server, whose v2 create-endpoint requires gpuPoolIds and has no CPU concept. Never use the public control REST POST https://rest.runpod.io/v1/endpoints with "computeType":"CPU" — it silently provisions a GPU endpoint instead (verified evidence in the Serverless command section below).
• Use templates when the user already has a template ID, wants reusable image/config defaults, or needs lower-level control than Hub.
• Use direct pod creation with --image when the user has a specific Docker image and does not need a saved template.
• Use serverless for request/response inference APIs and scalable workers; use pods for interactive work, notebooks, training, debugging, or long-lived sessions.
• Use CPU pods for preprocessing, file movement, lightweight scripts, and non-CUDA work. Use GPU pods when CUDA, model inference, training, or GPU memory is required.
• Do not pass GPU flags when creating CPU pods. Check runpodctl pod create --help for the current valid flag set.
• Waiting for a resource to be usable: use --wait, don't hand-roll a poll loop (v2.9.0+). create returns as soon as 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; serverless create --wait 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 that and clean up, don't assume nothing was created (a pod bills by the second; an endpoint with no running worker doesn't, but will start one on the first request).
• Standing up a service on a pod (Ollama, ComfyUI, a dev server)? Declare its --ports and --env at creation (they can't be added to a running pod without a reset), then follow the pod development loop in the runpod-usage skill (reference/pod-workflows.md) — SSH-exec the install, bind to 0.0.0.0, and poll the proxy URL until it answers.
• For SSH, use runpodctl pod get <pod-id> or runpodctl ssh info <pod-id> to retrieve connection details. runpodctl has no interactive-shell command — ssh info returns the connection command + key but does not connect. Run commands over SSH yourself with ssh user@host "command".
• Network volumes are location-sensitive. Check datacenter availability before attaching volumes, and use send / receive or S3-compatible storage for migrations.
• Clean up paid resources after tests: delete serverless endpoints, pods, and temporary volumes created for validation.
  • Cost guard on creation: use --terminate-after (deletes the pod); --stop-after only stops it, so disk/volume keep billing.
  • Attached volume: to delete a network volume, remove the pod using it first.

Serverless facts (context, not rules)

• Scale-to-zero billing: serverless endpoints scale to zero with --workers-min 0 (the default) — no GPU billing while idle, only per request-second; this is the right cost posture for a request/response API.
• Broken-image tell: if deployed workers go ready but jobs sit IN_QUEUE with inProgress: 0, the image is broken/mis-dispatching — the fix is to switch to a different worker rather than wait it out.
• Diagnosing it: read the worker/job counts with runpodctl serverless health <endpoint-id> (v2.9.0+), then read what the workers actually printed with runpodctl serverless logs <endpoint-id> (v2.10.0+) — no hand-built curl needed. Repeated system "start container" lines with no container output means the container exits before the handler runs.

Commands

Essentials below. For flags, ask the binary — runpodctl <resource> <action> --help, which is current by construction. reference/command-reference.md holds the part --help cannot answer: what a flag means when it succeeds, which field to trust, and what a failure looks like.

Pods

A stalled deploy shows up in --source system (v2.10.0+): repeated pull progress, or a create container that never reaches start. Use --source container for your workload's own output. Each line is one {source,line,ts} object, so pipe it straight to jq.

Read runtimeStatus, not desiredStatus, to decide whether a pod is usable (v2.9.0+): desiredStatus: RUNNING says that while the image is still pulling. Field meanings, reason tokens, and two edges (--status filters desiredStatus only; unknown = lookup failed, not pod down) → reference/command-reference.md.

Hub

Browse/search the Runpod Hub (curated deployable repos).

Serverless (alias: sls)

Invoke URLs come back with the endpoint. create/get/list/update include a urls object (run, runsync, health), so a freshly created endpoint is callable without a second lookup — read them instead of assembling the URL yourself. They're built from RUNPOD_INVOKE_URL (default https://api.runpod.ai/v2), which RUNPOD_API_URL/RUNPOD_GRAPHQL_URL do not move: reference/output-and-errors.md.

Reading worker logs (v2.10.0+) — also first-class, so worker output no longer requires the MCP lane or a hand-built SSE read:

Logs belong to a worker, not the endpoint, so without --worker this reads them all at once and tags each line with its workerId. The crash-loop tell: repeated system "start container" lines with no container output means the container exits before the handler runs — jobs then sit in the queue with nothing wrong with capacity.

Invoking an endpoint (v2.9.0+) — first-class commands, so an agent does not hand-build a curl request or manage a bearer token:

• Pass only the handler payload — the cli wraps it as {"input": <your json>} itself, so pasting a whole curl envelope double-wraps it.
• timeout means the cli stopped waiting, not that the endpoint broke. When the message names a serverless status command the job is still running server-side — poll it, do not re-invoke (that buys a second job).

Payload rules, the stdout/stderr split, exit codes and why /runsync is never used → reference/command-reference.md.

Create from hub: --hub-id resolves the hub listing, extracts the build image and config (GPU IDs, container disk, env vars), creates an inline template, and deploys. Accepts both SERVERLESS and POD listing types. GPU IDs and env var defaults from the hub config are included automatically; override with --gpu-id and --env.

CPU serverless endpoints (the always/never rule is in Decision Rules above): create with runpodctl serverless create --compute-type CPU (optionally --instance-id, e.g. cpu3g-4-16). Verified evidence for why the public REST must not be used: 2026-07-14, POST https://rest.runpod.io/v1/endpoints with "computeType":"CPU" silently returned a GPU endpoint (gpuCount:1, cpuFlavorIds:null), while runpodctl --compute-type CPU correctly returned computeType:"CPU" with instanceIds:["cpu3g-4-16"]. The MCP server is not an alternative here: its v2 create-endpoint requires gpuPoolIds and the v2 spec has no computeType/cpuFlavor field at all (verified 2026-07-29). The public control REST is v1-only (rest.runpod.io/v2 just redirects to docs). The separate runtime/invoke API https://api.runpod.ai/v2/<endpoint-id>/… (health/run/runsync/openai) is a different v2 and works fine — the v1-vs-v2 caveat here is only about the control/management REST.

Model cache (--model-reference): Attach a Hugging Face model to the endpoint by full URL with a ref, e.g. https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main. Runpod caches it host-side in the standard HF cache dir (/runpod-volume/huggingface-cache/hub/), so the worker loads it directly — no bake, no volume. Repeatable; works with --template-id/--hub-id, GPU only, runpodctl v2.4.0+. Full mechanics + how it compares to baking / network volume / the Model Repository: reference/model-caching.md. Worked end-to-end: golden path 20 — model-caching endpoint.

Multi-region / high-availability (--network-volume-ids): attach multiple network volumes (one per data center) so workers spread across DCs instead of being pinned to one — runpodctl serverless create --template-id <t> --network-volume-ids <v1>,<v2> --data-center-ids <dc1>,<dc2> …. Requires runpodctl ≥ v2.4.0 (older versions don't support multi-volume attach). Check runpodctl version; the Homebrew tap can lag, so prefer the GitHub releases binary. Data does not sync between volumes automatically — see golden path 10 — multi-region HA serverless.

For exact serverless flags, run runpodctl serverless <action> --help.

Templates (alias: tpl)

Network Volumes (alias: nv)

For exact network volume flags, run runpodctl network-volume <action> --help.

No storage-tier flag. create provisions the data center's default tier — there's no --type. To get a High-Performance volume, use the console (a ⚡ data center's toggle) or a raw v2 REST call (POST https://v2-rest.runpod.io/v2/network-volumes with "type":"HIGH_PERFORMANCE") — or the MCP create-network-volume tool, which takes volumeType (STANDARD | HIGH_PERFORMANCE). Tier is immutable after creation. Launch details: golden path 21.

Models (Model Repository)

runpodctl model manages the Runpod Model Repository — managed, versioned storage for your own model artifacts (upload once, distributed to workers; not pinned to a data center like a network volume). What it is, why/how, migrating off a baked-in model, and Model-Repo-vs-volume: reference/model-caching.md.

model add supports upload sessions, versioning, metadata, and private-source credentials — see live runpodctl model add --help.

Info & SSH

gpu list carries pricing and placement data — securePricePerHr / communityPricePerHr (explicitly null when that cloud doesn't offer the GPU) and a dataCenterAvailability[] breakdown. Read the breakdown, not just top-level stockStatus (which is only the best status across DCs), when a create has to schedule in a specific DC — and pass --include-unavailable, since the default listing hides no-stock GPUs and can omit one that has stock only in the DC you want. The prices are pod on-demand rates. Shape, stock-value vocabulary and the "none" vs omitted-key sentinel: reference/output-and-errors.md.

ssh info gives connection details, not a session — if interactive SSH isn't available, run ssh user@host "command". Registry auth, billing history, and SSH key management (ssh add-key/remove-key) are in reference/command-reference.md.

File Transfer

Encrypted/incremental/compressed — don't pre-tar. Key gotchas: capture the first line of send stdout (the code) as it streams (background + tee), each send mints a fresh code, both sides must exit 0. Full agent flow (pod push via ssh + receive): reference/command-reference.md.

Utilities

URLs

Pod URLs

Access exposed ports on your pod:

Example: https://abc123xyz-8888.proxy.runpod.net

Serverless URLs

Prefer runpodctl serverless run|status|health (above) — same api, with auth, validation and bounded polling handled. Use the raw urls for what the commands don't cover: streaming, the OpenAI-compatible route, or a copy-paste curl for a user.

serverless create/get/list/update already return run/runsync/health in a urls object — prefer those over hand-assembling, since a non-default RUNPOD_INVOKE_URL changes the base. Only status/<job-id> has to be built by hand.

Source & docs

• CLI source: https://github.com/runpod/runpodctl
• Releases (binaries): https://github.com/runpod/runpodctl/releases
• Docs: https://docs.runpod.io/runpodctl/overview