runpodctl cli

runpodctl is the cli tool to manage gpu pods, serverless endpoints, and more on runpod.io.

note: all pods automatically come with runpodctl installed with a pod-scoped api key.

table of contents

• runpodctl cli
  • table of contents
  • get started
    • install
      • linux/macos (wsl)
      • macos
      • windows powershell
      • conda, mamba, pixi (conda-forge)
      • nix
  • quick start
  • commands
    • pod management
    • serverless endpoints
      • reading logs
      • invoking an endpoint
    • waiting until a resource is usable
    • file transfer
  • output format
    • pod runtime status
    • error format
  • environment variables
    • config permissions
  • update prompt
  • legacy commands
  • release process
  • acknowledgements

get started

install

linux/macos (wsl)

curl -fsSL https://cli.runpod.net | sudo bash

macos

brew install runpod/runpodctl/runpodctl

windows powershell

installs to %LOCALAPPDATA%\runpodctl and puts it on your PATH, so runpodctl works from any terminal. for arm64, swap amd64 for arm64 in the url.

$dest = "$env:LOCALAPPDATA\runpodctl"
Invoke-WebRequest -UseBasicParsing -Uri https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.zip -OutFile "$env:TEMP\runpodctl.zip"
Expand-Archive -Force -Path "$env:TEMP\runpodctl.zip" -DestinationPath $dest
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
$pathEntries = @($userPath -split ';' | Where-Object { $_ })
if ($pathEntries -notcontains $dest) {
  [Environment]::SetEnvironmentVariable('Path', (($pathEntries + $dest) -join ';'), 'User')
}

then open a new terminal so the PATH change takes effect.

conda, mamba, pixi (conda-forge)

runpodctl is available on conda-forge.

# conda
conda install conda-forge::runpodctl

# mamba
mamba install conda-forge::runpodctl

# pixi (user-global install)
pixi global install runpodctl

nix

run it straight from github, or install it into your profile (linux and apple silicon):

nix run github:runpod/runpodctl -- pod list
nix profile install github:runpod/runpodctl

runpodctl update cannot replace a binary in the read-only nix store; upgrade with nix profile upgrade instead. the flake also provides the dev shell, hermetic checks, oci images and the static analysis report: see nix/README.md.

quick start

# configure api key (prompts for it)
runpodctl doctor

# or non-interactive (ci, containers, agents). stdin keeps the key out of
# shell history and ps; --api-key also works and replaces a saved key
printf %s "$MY_RUNPOD_KEY" | runpodctl doctor

# list all pods
runpodctl pod list

# get a specific pod
runpodctl pod get pod_id

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

# start/stop/delete a pod
runpodctl pod start pod_id
runpodctl pod stop pod_id
runpodctl pod delete pod_id

commands

commands follow noun-verb pattern: runpodctl <resource> <action>

pod management

runpodctl pod list                    # list all pods
runpodctl pod get <id>                # get pod details
runpodctl pod logs <id>               # read a pod's logs (--follow to stream)
runpodctl pod create --image=<img>    # create a pod
runpodctl pod update <id>             # update a pod
runpodctl pod start <id>              # start a stopped pod
runpodctl pod stop <id>               # stop a running pod
runpodctl pod delete <id>             # delete a pod

serverless endpoints

runpodctl serverless list             # list endpoints (alias: sls)
runpodctl serverless get <id>         # get endpoint details
runpodctl serverless create           # create endpoint
runpodctl serverless update <id>      # update endpoint
runpodctl serverless delete <id>      # delete endpoint
runpodctl serverless health <id>      # worker and job counts for an endpoint
runpodctl serverless logs <id>        # read worker logs (--follow to stream)
runpodctl serverless run <id>         # invoke an endpoint and wait for the result
runpodctl serverless status <id> <job-id>  # check a job submitted earlier

reading logs

pod logs and serverless logs stream from rest v2 (api.runpod.io/v2). output is json lines — one {source,line,ts} object per line, plus workerId on serverless — so it pipes into jq or an agent without further parsing.

runpodctl pod logs <id> --tail 50            # replay recent lines and exit
runpodctl pod logs <id> --follow             # stream until interrupted
runpodctl pod logs <id> --since 30m          # a time window instead of a line count
runpodctl pod logs <id> --source system      # platform lines only
runpodctl serverless logs <id>               # every worker, tagged with workerId
runpodctl serverless logs <id> --worker <wid>  # one worker

behavior worth knowing, all verified against prod:

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗