Overview

Use Runpod CLI to manage Pods, Serverless endpoints, templates, and more from your local machine. Review commands and usage guidance for the Runpod CLI.

Runpod CLI is an open source command-line tool for managing your Runpod resources from your local machine. You can manage Pods, Serverless endpoints, templates, network volumes, and models, transfer files between your system and Runpod, diagnose issues, and view account information.

Quick start

After installing and configuring runpodctl, you can start managing resources immediately:

runpodctl doctor                    # First time setup (API key + SSH)
runpodctl gpu list                  # See available GPUs
runpodctl template search pytorch   # Find a template
runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA RTX 4090"
runpodctl pod list                  # List your Pods

Install Runpod CLI locally

Every you deploy comes preinstalled with runpodctl and a Pod-scoped API key. You can also install it on your local machine to manage resources remotely.

Step 1: Choose an installation method

Choose the installation method that matches your operating system.

Install script

The install script automatically detects your operating system and architecture:

bash <(wget -qO- cli.runpod.io)

Or using curl:

bash <(curl -sL cli.runpod.io)

The script installs the latest version to /usr/local/bin when run as root, or to ~/.local/bin for non-root users. If you don’t have root access, the script displays instructions for adding runpodctl to your PATH.

macOS

Homebrew:

brew install runpod/runpodctl/runpodctl

ARM (Apple Silicon):

wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-darwin-arm64 -O runpodctl && chmod +x runpodctl && sudo mv runpodctl /usr/local/bin/runpodctl

AMD (Intel):

wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-darwin-amd64 -O runpodctl && chmod +x runpodctl && sudo mv runpodctl /usr/local/bin/runpodctl

Linux

AMD64 (x86_64):

wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64 -O runpodctl && chmod +x runpodctl && sudo cp runpodctl /usr/bin/runpodctl

ARM64 (aarch64):

wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-arm64 -O runpodctl && chmod +x runpodctl && sudo cp runpodctl /usr/bin/runpodctl

Non-root installation:

If you don’t have root access, install to your user directory:

mkdir -p ~/.local/bin && wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64 -O ~/.local/bin/runpodctl && chmod +x ~/.local/bin/runpodctl

Then add ~/.local/bin to your PATH by adding this line to your ~/.bashrc or ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Windows

wget https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.exe -O runpodctl.exe

Google Colab / Jupyter Notebook

!wget --quiet --show-progress https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64 -O runpodctl
!chmod +x runpodctl
!cp runpodctl /usr/bin/runpodctl

conda / mamba / pixi

Pre-built binaries are available on conda-forge for Linux (x86_64, aarch64, ppc64le), macOS (x86_64, arm64), and Windows (x86_64).

conda:

conda install conda-forge::runpodctl

mamba:

mamba install conda-forge::runpodctl

pixi:

pixi global install runpodctl

This installs runpodctl globally on your system, so you can run commands from any directory.

Step 2: Configure your API key

Before you can use runpodctl locally, you must configure it with an API key.

The easiest way to set up your API key and SSH configuration is with the doctor command:

runpodctl doctor

This command guides you through first-time setup, including API key configuration and SSH key setup.

Alternatively, you can manually configure your API key:

runpodctl config --apiKey YOUR_API_KEY

After running the command, you should see a confirmation message similar to this:

saved apiKey into config file: /Users/runpod/.runpod/config.toml

Step 3: Verify installation

To verify that runpodctl installed successfully, run this command:

runpodctl version

You should see which version is installed:

runpodctl v2.0

Command groups

Runpod CLI organizes commands into groups based on the resource type:

Command	Alias	Description
runpodctl pod		Manage Pods (create, list, start, stop, delete)
runpodctl serverless	sls	Manage Serverless endpoints
runpodctl template	tpl	List, search, and manage templates
runpodctl hub		Browse and deploy from the Runpod Hub
runpodctl network-volume	nv	Manage network volumes
runpodctl registry	reg	Manage container registry authentications
runpodctl gpu		List available GPUs
runpodctl datacenter	dc	List datacenters
runpodctl billing		View billing history
runpodctl user	me	View account information
runpodctl ssh		Manage SSH keys and get connection info

Help and reference

Learn how to use Runpod CLI commands by browsing the CLI reference using the sidebar to the left, or by running the help command:

runpodctl help

Learn more about a particular command by running:

runpodctl [command] --help

Output format

Successful command output goes to standard output as JSON by default, which makes runpodctl scriptable and agent-friendly. Use the --output flag to switch to a human-readable table or YAML:

runpodctl pod list                    # json (default)
runpodctl pod list --output=table     # table
runpodctl pod list --output=yaml      # yaml

template search and hub search emit [] on standard output when nothing matches, instead of a prose message, so a caller piping the output into a JSON parser gets a valid empty list on the no-match case.

Error format

When a command fails, runpodctl writes a single flat JSON object to standard error and exits with a non-zero status. Branch on the code field, never on the message text:

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

Field	Description
error	Human-readable message, unwrapped (never a nested JSON blob).
code	Stable, lowercase identifier for the failure class. Present on every error from the resource commands.
status	HTTP status code. Only present when the failure came back from a REST call. Absent when the API answered 200 with an empty result (GraphQL reports missing resources this way), so branch on code rather than status.

Codes runpodctl generates:

Code	Meaning
usage_error	The invocation was wrong: unknown command or flag, bad or missing arguments, missing required flags. Usage text is printed after the JSON object.
not_found	The resource does not exist.
bad_request, unauthorized, forbidden, conflict, rate_limited, server_error, api_error	Derived from the REST status returned by the API.
graphql_error	GraphQL returned an errors array (HTTP 200).
no_credentials	No API key is configured. Run runpodctl doctor or set RUNPOD_API_KEY.
network_error	The API could not be reached (DNS failure, connection refused, TLS error, timeout). This is the only code that means “transient, retry.”
cli_error	Any other local failure: validation, config, bad input, malformed RUNPOD_API_URL.

The API can also return its own code, which is passed through in lowercase. Treat the list above as the set the CLI generates rather than an exhaustive one.

Exit codes

Every documented resource command exits non-zero on failure, including model, update, send, and receive (which previously exited 0 on some failure paths). Do not rely on stdout being empty to detect failure. Check the exit code and parse the JSON error object on stderr.

A few legacy surfaces still print plain-text errors and do not carry a code:

• The legacy pod verbs (get pod, create pod, remove pod, start pod, stop pod, create pods, remove pods) and get cloud print Error: <message> via cobra and exit 1.
• exec prints plain text and exits 1.
• project prints to standard output and exits 0 on failure (tracked upstream).

Parsers should tolerate a non-JSON line on stderr from those commands, and should not rely on the exit code for project until the upstream fix lands.

Environment variables

Variable	Default	Description
RUNPOD_API_KEY	—	API key. Also settable via runpodctl doctor or ~/.runpod/config.toml.
RUNPOD_API_URL	https://rest.runpod.io/v1	REST control plane (config key restApiUrl).
RUNPOD_GRAPHQL_URL	https://api.runpod.io/graphql	GraphQL control plane (config key apiUrl).
RUNPOD_INVOKE_URL	https://api.runpod.ai/v2	Base URL used to build the Serverless invoke URLs reported by serverless create/get/list (config key invokeUrl).

Invoke is a separate service from the control plane. Pointing RUNPOD_API_URL or RUNPOD_GRAPHQL_URL at a non-production host does not move the invoke URLs; override RUNPOD_INVOKE_URL explicitly when you need that.

Shell completion

Enable tab completion for your shell to make working with runpodctl easier:

runpodctl completion

This command auto-detects your shell and adds the appropriate source command to your shell configuration file (~/.bashrc or ~/.zshrc). The command is idempotent—running it again skips installation if completion is already configured.

Restart your shell or source the configuration file for changes to take effect.