Subcommands
List Pods
List your Pods. By default, this command shows only running Pods and Pods in an error state (similar todocker ps). Pods in an error state are included because they still exist and may still incur charges:
List flags
Show all Pods including exited ones. By default, only running Pods and Pods in an error state are shown.
Filter by desired status (
desiredStatus), such as RUNNING or EXITED. Matching is case-insensitive. Does not accept runtimeStatus values like initializing; passing one returns no results. Cannot be used with --all.Filter Pods created within the specified duration (e.g.,
1h, 24h, 7d). Cannot be used with --created-after.Filter Pods created after the specified date in
YYYY-MM-DD format. Cannot be used with --since.Get Pod details
Get detailed information about a specific Pod, including SSH connection info:Get flags
Include the Pod’s placement: its datacenter ID (
dataCenterId) and whether it runs on Secure Cloud (secureCloud).Create a Pod
Create a new Pod from a template:Create flags
Template ID to use for Pod configuration. Use
runpodctl template search to find templates.Docker image to use (e.g.,
runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04). Required if no template specified.Custom name for the Pod. If you don’t set one, the Pod is named after its image without the tag (for example,
runpod/pytorch). A Pod created from a template without --image is named after the template ID.GPU type (e.g.,
NVIDIA GeForce RTX 4090, NVIDIA A100 80GB PCIe). Required for GPU Pods, and not supported for CPU Pods. Use runpodctl gpu list to see available GPUs.Persistent volume size in GB. CPU Pods can’t have a persistent volume. You also can’t combine this flag with
--network-volume-id because a network volume takes the place of the persistent volume.Cloud tier (
SECURE or COMMUNITY). Community Cloud Pods aren’t guaranteed a public IP address, so their SSH port may not be publicly reachable. Use Secure Cloud if you need SSH access.Comma-separated list of preferred datacenter IDs. Use
runpodctl datacenter list to see available datacenters.Network volume ID to attach. Use
runpodctl network-volume list to see available network volumes.Minimum CUDA version required (e.g.,
11.8, 12.4). The Pod will only be scheduled on machines that meet this CUDA version requirement.Container registry authentication ID for pulling private images. Use
runpodctl registry list to see available registry credentials.Country code that restricts Pod placement to datacenters in that country (e.g.,
US, DE). Supported only for GPU Pods on Secure Cloud. For CPU Pods, use --data-center-ids instead.Comma-separated list of compliance certifications the datacenter must hold (e.g.,
HIPAA,SOC_2_TYPE_2). Supported only on Secure Cloud.Start a Pod
Start a stopped Pod:Stop a Pod
Stop a running Pod:Restart a Pod
Restart a Pod:Update a Pod
Update Pod configuration:Update flags
Delete a Pod
Delete a Pod:Pod runtime status
runpodctl pod get and runpodctl pod list report a Pod’s real runtime state in their JSON and YAML output, alongside the existing desiredStatus. desiredStatus is the state you asked for (for example, RUNNING), while runtimeStatus is what the Pod is actually doing. For example, a Pod still pulling a large image and a Pod that has been serving traffic for an hour both show desiredStatus: RUNNING, but their runtimeStatus values differ.
For example, runpodctl pod list --output json returns entries like this for a running Pod:
runtimeStatus is initializing, runtimeStatusReason is awaiting_container, and uptimeSeconds is omitted because no container is reporting yet.
Runtime status values
Runtime status reasons
The API doesn’t record why a Pod stopped in a machine-readable form, so
stopped, terminated, and error have no reason token.
runtimeStatus and desiredStatus come from the same API read, so they always agree on the Pod’s state.
The uptimeSeconds field reports the container’s uptime and is omitted when no container is reporting.
Pod URLs
Access exposed ports on your Pod using the following URL pattern:abc123xyz and you exposed port 8888: