runpod/runpodctl

runpodctl – CLI for Runpod GPU resources

What it is – runpodctl is a command‑line client that talks to the Runpod platform (runpod.io). It lets you create, list, start, stop and delete GPU‑powered pods, as well as manage serverless “endpoints” (functions that run on Runpod’s infrastructure). All of the heavy lifting (API calls, authentication, log streaming) is hidden behind simple commands.

Why you’d use it – When you need on‑demand GPU compute for training, inference, or any other AI workload, Runpod provides the cloud machines. runpodctl gives you a quick, scriptable way to spin those machines up, inspect logs, transfer files, and invoke serverless functions without writing raw HTTP requests.

Installation – The tool can be installed in several ways:

• One‑liner script for Linux/macOS (including WSL): wget -qO- cli.runpod.net | sudo bash
• Homebrew on macOS: brew install runpod/runpodctl/runpodctl
• Windows PowerShell script that downloads a zip, extracts it to %LOCALAPPDATA%\runpodctl, and adds it to your PATH.
• Conda‑forge (conda, mamba, pixi): conda install conda-forge::runpodctl (or the equivalent mamba/pixi command).

Basic workflow

# set your API key (once)
runpodctl config --apiKey=YOUR_KEY

# see what you have
runpodctl pod list
runpodctl pod get POD_ID

# launch a new GPU pod
runpodctl pod create \
  --image=runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04 \
  --gpu-id=NVIDIA_A100

# control its lifecycle
runpodctl pod start POD_ID
runpodctl pod stop POD_ID
runpodctl pod delete POD_ID

Serverless endpoints – Similar commands exist for the “serverless” product:

• runpodctl serverless list / create / update / delete
• runpodctl serverless run ID --input '{"prompt":"hello"}' to invoke a function and wait for the result.
• Log streaming (runpodctl serverless logs ID) works the same way as pod logs, outputting JSON‑lines that can be piped to tools like jq.

Log handling – Both pod and endpoint logs are streamed from a separate API endpoint in JSON‑lines format ({source,line,ts}), with optional flags:

• --tail N – show the last N lines per source.
• --follow – keep the stream open.
• --since <duration> – filter by time.
• --source system|container – choose platform vs. workload output.

Waiting for resources – Adding --wait to pod create or serverless create blocks until the resource is actually reachable (SSH for pods, health check for endpoints). Timeouts can be tuned with --wait-timeout.

File transfer – runpodctl send FILE generates a short code; the peer runs runpodctl receive CODE to pull the file using the croc protocol. The tool validates paths to avoid writing outside the current directory.

Output formats – By default commands emit JSON, but you can request YAML with --output=yaml. Invalid format names are rejected with a clear error.

Error handling – Errors are returned as JSON objects containing a code (e.g., usage_error, wait_timeout) and a human‑readable error field. Exit codes follow the rule: 0 for success, non‑zero for failures, timeouts, or job failures.

Who benefits – Data scientists, ML engineers, or anyone needing programmatic control over Runpod’s GPU pods and serverless endpoints can embed these commands in scripts, CI pipelines, or interactive sessions.

---

All details above are taken directly from the README of the runpod/runpodctl repository.