runpod/runpodctl

What runpodctl does

runpodctl is a command‑line client for RunPod, a cloud service that lets you spin up GPU‑backed containers (called pods) and serverless inference endpoints. With the tool you can create, start, stop, delete, and inspect those resources, as well as invoke serverless functions and transfer files, all from a terminal.

Who might use it

• AI researchers / developers who need on‑demand GPU machines for training or experimentation.
• ML engineers deploying inference models as serverless endpoints and wanting a quick way to test or monitor them.
• Automation scripts or AI agents that need to programmatically provision compute without writing HTTP calls.

Core capabilities

Area	Commands (noun‑verb style)	What it lets you do
Pod management	runpodctl pod list/get/create/update/start/stop/delete	List existing GPU pods, inspect a pod, launch a new pod from a Docker image, change its configuration, control its lifecycle.
Serverless endpoints	runpodctl serverless list/get/create/update/delete/run/status/health	Manage “serverless” inference services, invoke them with JSON payloads, poll job status, check worker health.
Waiting for readiness	--wait (on pod create or serverless create)	Block until SSH on a pod is reachable or a serverless worker reports ready/running, saving you a manual poll loop.
File transfer	runpodctl send <file> / runpodctl receive <code>	Transfer files between machines using the peer‑to‑peer tool croc without needing an API key.
Output formatting	`--output=json	yaml
Error handling	Consistent JSON error objects on stderr with a stable code field	Scripts can reliably branch on error codes (not_found, usage_error, wait_timeout, etc.) instead of parsing free‑form messages.

Typical workflow (quick start)

# 1️⃣ Store your RunPod API key once
runpodctl config --apiKey=YOUR_KEY

# 2️⃣ List current pods
runpodctl pod list

# 3️⃣ Spin up a new GPU pod (example PyTorch image on an A100)
runpodctl pod create \
  --image=runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04 \
  --gpu-id=NVIDIA_A100

# 4️⃣ When you’re done, shut it down
runpodctl pod stop <pod_id>
runpodctl pod delete <pod_id>

The same pattern works for serverless endpoints, e.g. runpodctl serverless run <id> --input '{"prompt":"hello"}'.

Installation options

Platform	Command
Linux/macOS (including WSL)	wget -qO- cli.runpod.net | sudo bash
macOS (Homebrew)	brew install runpod/runpodctl/runpodctl
Windows PowerShell	wget https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.exe -O runpodctl.exe
Conda / Mamba / Pixi	conda install -c conda-forge runpodctl (or mamba, pixi global install)

Design notes that matter to developers

• JSON‑first output: By default every successful command prints a single JSON object to stdout. This makes the CLI easy to consume from other programs or LLM‑driven agents.
• Separate stdout / stderr: Data (pod info, job payload) goes to stdout, while progress messages and error objects go to stderr. This avoids mixing streams.
• Stable error codes: Every error includes a lowercase code (e.g., not_found, rate_limited). Scripts should switch on this field rather than on HTTP status or free‑form text.
• Wait semantics: --wait blocks until a resource is usable (SSH reachable for pods, at least one ready worker for serverless). Timeouts are configurable (--wait-timeout). Interrupting a wait does not delete the resource; the CLI returns the resource ID so you can clean up later.
• No hidden synchronous endpoint: The CLI always uses the asynchronous /run API and polls /status. This avoids the pitfalls of the /runsync endpoint (billing‑run orphaning, short result retention).

When you might not need it

If you only ever use RunPod through its web UI or a higher‑level SDK, installing runpodctl adds little value. It shines when you need a lightweight, scriptable interface that works in CI pipelines, remote shells, or as part of an autonomous AI agent.

---

All details above are taken directly from the project's README; no additional features have been inferred.