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.Block until the Pod is reachable over SSH, then print the Pod as
pod get does. The CLI checks that the Pod’s public port 22 answers, so it needs no key. This requires a publicly mapped port 22, which Community Cloud doesn’t always provide.What
--wait waits for: ssh (default; port 22 is reachable) or running (the Pod’s container is up). Use running for images without an SSH server or with --ssh=false. Setting this flag implies --wait.Maximum time to wait with
--wait, such as 90s, 10m, or 1h (default 10m). On timeout, the Pod is kept and the error includes its ID.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:Read Pod logs
Read a Pod’s container and system logs:source, line, and ts fields, so you can pipe it to jq. The container source is your workload’s own output. The system source is the platform reporting image pull, container create, and start. A stalled deployment usually shows up there, as repeated pull progress or a create that never reaches start.
Logs flags
Keep streaming new lines until you interrupt the command. Without it, the command replays recent lines and exits once they stop arriving.
Number of historical lines to replay before live output, from 0 to 5000 (default
100). Use 0 for live output only.Only show logs after this point: a duration such as
30m, 2h, or 7d, or an RFC 3339 timestamp. Overrides --tail.Which log source to read:
container (your workload’s own output), system (platform events such as image pull, container create, and start), or both (default).How long to wait for output before exiting when not following (default
5s). The command exits earlier once the replayed lines stop arriving.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: