From b093bd7dcde141f64a81182f3622c434148abc9a Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 6 Aug 2026 13:10:16 +0000
Subject: [PATCH] docs: document --wait and --wait-timeout for runpodctl
pod/serverless create
---
runpodctl/reference/runpodctl-pod.mdx | 33 ++++++++++++++++++++
runpodctl/reference/runpodctl-serverless.mdx | 23 ++++++++++++++
2 files changed, 56 insertions(+)
diff --git a/runpodctl/reference/runpodctl-pod.mdx b/runpodctl/reference/runpodctl-pod.mdx
index 3ae1c05b4..ab4b98d80 100644
--- a/runpodctl/reference/runpodctl-pod.mdx
+++ b/runpodctl/reference/runpodctl-pod.mdx
@@ -98,6 +98,14 @@ Create a CPU-only Pod:
runpodctl pod create --compute-type cpu --image ubuntu:22.04
```
+Block until the Pod's SSH is reachable, then print the same output as `pod get` (including the live `ssh` block):
+
+```bash
+runpodctl pod create --image "runpod/pytorch:1.0.3-cu1281-torch291-ubuntu2404" --gpu-id "NVIDIA GeForce RTX 4090" --wait
+```
+
+See [Wait for the Pod to be usable](#wait-for-the-pod-to-be-usable) for details on `--wait` and `--wait-timeout`.
+
#### Create flags
@@ -196,6 +204,31 @@ Automatically terminate the Pod after the specified duration (e.g., `1h`, `24h`,
Compliance settings for the Pod (e.g., regulatory requirements for data handling).
+
+Block until the Pod is actually usable, not just scheduled. See [Wait for the Pod to be usable](#wait-for-the-pod-to-be-usable).
+
+
+
+Maximum time to wait when `--wait` is set. Accepts values like `90s`, `10m`, `1h`, `2d`. On timeout the Pod is kept (it is billing) and the error carries its `id`.
+
+
+#### Wait for the Pod to be usable
+
+By default, `pod create` returns as soon as the Pod is scheduled. Its container image may still be pulling and sshd may not be running yet. Pass `--wait` to block until the Pod is reachable over SSH before the command returns:
+
+```bash
+runpodctl pod create --image --gpu-id "NVIDIA GeForce RTX 4090" --wait
+```
+
+**Readiness predicate.** With `--wait`, the CLI polls the Pod's public port `22` and considers it ready once a TCP connection succeeds and the server replies with an SSH protocol banner. There is no key check or full handshake, so the wait can succeed against an image whose sshd never received your key. When ready, `pod create` prints the same shape as [`runpodctl pod get`](#get-pod-details) rather than the plain create response, so the payload includes the live `ssh` block.
+
+**Timeout behavior.** `--wait-timeout` defaults to `10m` and shares the CLI's duration parser (`90s`, `10m`, `1h`, `2d`). If the wait times out or you cancel with `Ctrl-C`, **the Pod is not deleted** — you are still billed for it. The command exits non-zero, and the error object carries an `id` field with the Pod ID plus a `code` of `wait_timeout` or `wait_interrupted` so you can clean up with [`runpodctl pod delete`](#delete-a-pod).
+
+**Flag compatibility.** `--wait` requires SSH, so it cannot be combined with `--ssh=false`. Two other combinations still work but print a warning on stderr because they often fail to produce a reachable SSH port:
+
+- `--compute-type CPU` — CPU Pods are created over REST and do not get Runpod-managed SSH, so only images that start their own sshd become reachable.
+- `--cloud-type COMMUNITY` without `--public-ip` — Community Cloud only maps a public SSH port when the machine has a public IP.
+
### Start a Pod
Start a stopped Pod:
diff --git a/runpodctl/reference/runpodctl-serverless.mdx b/runpodctl/reference/runpodctl-serverless.mdx
index a80cd6f13..136f36c3e 100644
--- a/runpodctl/reference/runpodctl-serverless.mdx
+++ b/runpodctl/reference/runpodctl-serverless.mdx
@@ -84,6 +84,9 @@ runpodctl serverless create --hub-id cm8h09d9n000008jvh2rqdsmb --gpu-id "NVIDIA
runpodctl serverless create --hub-id cm8h09d9n000008jvh2rqdsmb --name "my-vllm" \
--env MODEL_NAME=meta-llama/Llama-3.1-8B-Instruct \
--env MAX_TOKENS=4096
+
+# Block until a worker is ready before returning
+runpodctl serverless create --template-id "tpl_abc123" --gpu-id "NVIDIA GeForce RTX 4090" --workers-min 1 --wait
```
When using `--hub-id`, GPU IDs and container disk size are automatically pulled from the Hub release config. You can override the GPU type with `--gpu-id`. Environment variables from the Hub release are included automatically, and you can override or add to them with `--env`.
@@ -178,6 +181,26 @@ Environment variable in `KEY=VALUE` format. Use multiple `--env` flags to set mu
Model reference URL to attach to the endpoint. Use multiple `--model-reference` flags to attach multiple models. Works with both `--template-id` and `--hub-id`, and requires GPU compute type.
+
+Block until the endpoint has a ready or running worker before returning. See [Wait for a ready worker](#wait-for-a-ready-worker).
+
+
+
+Maximum time to wait when `--wait` is set. Accepts values like `90s`, `10m`, `1h`, `2d`. On timeout the endpoint is kept (it may be billing) and the error carries its `id`.
+
+
+#### Wait for a ready worker
+
+By default, `serverless create` returns as soon as the endpoint is created, before any worker has come up. Pass `--wait` to block until the endpoint is actually able to serve traffic:
+
+```bash
+runpodctl serverless create --template-id --workers-min 1 --wait
+```
+
+**Readiness predicate.** With `--wait`, the CLI polls the endpoint's `/health` and considers it ready once `ready > 0` or `running > 0` — that is, at least one worker is warm (flashboot-cached and available to resume on the next request) or already scheduled. `--workers-min 1` is the fastest way to reach the ready state because it starts (and bills for) a worker immediately.
+
+**Timeout behavior.** `--wait-timeout` defaults to `10m` and accepts values like `90s`, `10m`, `1h`, `2d`. If the wait times out or you cancel with `Ctrl-C`, **the endpoint is not deleted**. The command exits non-zero, and the error object carries an `id` field with the endpoint ID plus a `code` of `wait_timeout` or `wait_interrupted` so you can clean up with [`runpodctl serverless delete`](#delete-an-endpoint).
+
### Update an endpoint
Update endpoint configuration: