runpodctl

Runpodctl

管理 GPU Pod、无服务器端点、模板、卷和模型。

对于无服务器开发工作流，无论 CLI 版本如何，都请使用 Runpod SDK。

安装

curl -sSL https://cli.runpod.net | bash（Linux/macOS，以及通过 WSL 使用的 Windows）或 brew install runpod/runpodctl/runpodctl。手动二进制文件、Windows 和 conda 的安装步骤见runpodctl README，其中也提供了这些步骤所说明的 install.sh。命令范围由二进制文件决定——runpodctl <resource> <action> --help——或由 runpodctl/docs/ 下生成的页面决定。

旧版 runpodctl 会悄无声息地缺少较新的标志/行为（例如，v2.4.0 之前不存在 --model-reference），并导致令人困惑的后续错误——而 Homebrew tap 可能会严重滞后。因此，在开始任何工作之前：

• 更新到最新版本——检查 runpodctl version，然后运行 runpodctl update （或从最新版本重新安装）。
• 整个任务都固定使用同一个较新版本。
• 任务中途切勿在旧版和新版二进制文件之间切换（这种来回切换是已知的故障原因）。
• 验证一次——继续操作前，确认 runpodctl version 显示当前版本。

快速开始

runpodctl update                    # FIRST: get on the latest build — old versions cause confusing errors
runpodctl version                   # confirm the current version before doing any work
export RUNPOD_API_KEY=your_key      # Non-interactive auth (agents) — runpodctl reads this
runpodctl doctor                    # Interactive first-time setup (API key + SSH) — for humans
runpodctl --help                    # See current top-level commands
runpodctl pod create --help         # Inspect exact current flags before creating
runpodctl gpu list                  # See available GPU types
runpodctl datacenter list           # GPU availability per data center (use to co-locate GPU + volume)
runpodctl hub search vllm           # Find a hub repo
runpodctl serverless create --hub-id <id> --name "my-vllm"  # Deploy from hub
runpodctl template search pytorch   # Find a template
runpodctl pod create --template-id runpod-torch-v280 --gpu-id "NVIDIA GeForce RTX 4090" --min-cuda-version 12.8  # Create from template
runpodctl pod list                  # List your pods

身份验证：Agent 应使用 export RUNPOD_API_KEY=...（非交互式）。runpodctl doctor 是交互式命令（会提示输入），还会设置 SSH 密钥——适合人类首次运行，不适合脚本使用。

API 密钥：https://console.runpod.io/user/settings

实时帮助具有权威性

实时的 runpodctl --help 输出是标志、别名和命令语法的准确信息来源。工作流、决策规则、安全提示和常见示例请参考此技能。

runpodctl --help
runpodctl <resource> --help
runpodctl <resource> <action> --help

使用不熟悉的命令前，请先查看实时帮助。不要将此技能视为详尽的标志参考。

**实时帮助不涵盖的内容：**输出格式、错误代码和退出代码行为。--help 会列出标志，但不会展示失败时的情况。有关这些内容，请参阅 reference/output-and-errors.md——如有疑问，请实际探测二进制文件：故意错误地运行命令（runpodctl serverless get nope），然后查看它输出的 JSON。每份文档都只是某一时点的快照，此技能也不例外；以你手头的二进制文件为准。

输出与错误

数据以 JSON 格式写入 stdout（--output=yaml 是唯一替代格式——没有表格格式；其他任何值都会静默返回 JSON）。资源命令失败时，会在 stderr 上输出一个扁平的 JSON 对象，并以 非零状态码退出：

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

根据 code 分支判断，绝不要根据 status 或消息判断。 只有当失败来自非 2xx 响应时才会有 status——GraphQL 会将缺失资源报告为 HTTP 200 + null 数据，因此 if status == 404 会漏掉所有 GraphQL 未找到错误。

code	处理方式
network_error	退避重试——这是唯一表示“无法连接 API”的代码
rate_limited server_error	退避重试——API 返回了 429/5xx
usage_error cli_error bad_request not_found conflict	不要重试，修正输入
no_credentials	未设置密钥：export RUNPOD_API_KEY=… 或 runpodctl doctor
unauthorized forbidden	已设置密钥，但密钥错误、已过期或缺少访问权限——不要重试，也不要再次提示输入缺失的密钥
其他任何值	视为致命错误，原样显示 error——API 可能会透传自己的代码

runpodctl 不会在内部重试；它不会为你执行退避。

• not_found 始终表示 API 缺少该资源，绝不表示本地路径拼写错误（后者是 cli_error）。
• **cli_error 是一个混合类别：**本地环境问题，以及命令自行验证的调用错误（例如，ssh remove-key 既没有 --name 也没有 --fingerprint）。只有 cobra 强制要求的必填标志才属于 usage_error。
• usage_error = 未知命令/标志、参数错误、缺少 cobra 强制要求的标志；JSON 后面会附带用法文本。运行时错误不再打印用法。
• stderr 非空不代表失败——成功时，弃用的 warning: 和 note: 行也会写入 stderr。先根据退出码判断，再解析 stderr。

带代码的错误、无服务器的 urls 对象和 GPU 定价都需要 runpodctl ≥ v2.8.0。旧版二进制会输出 {"error":"…"}，不包含 code 和 status——它仍然是 JSON 格式，因此 switch (err.code) 会静默得到 undefined，而不是明确报错。请检查是否存在 code，不要根据 JSON 还是纯文本判断；runpodctl version 不可靠，因为源码构建或自定义构建可能会报告已发布版本或占位符。

project 的行为取决于构建版本。 在截至 v3.0.1 的已发布版本中，运行时错误会输出到 stdout 并以 0 退出，因此请检查输出。在包含尚未发布的 runpod/runpodctl#382 的构建版本中，runpodctl project ... 调用（包括子命令、别名和标志）会以 1 退出，stdout 为空，并在 stderr 上打印 Runpod SDK 通知。project --help、help project、-h project 和 --help project 等帮助形式也遵循此约定。将该通知视为致命错误，原样显示，并且不要重试或要求 JSON。请检查 runpodctl version，但对于源码构建或自定义构建，请核实提交记录：其版本字符串可能与已发布版本一致。

完整代码表、纯文本例外情况、Runpod SDK 通知原文以及环境变量表（包括 RUNPOD_INVOKE_URL）： reference/output-and-errors.md。

决策规则

• 当用户需要已知且可部署的应用或 worker（例如 vLLM、ComfyUI、Whisper，或由 Runpod 维护的仓库）时，使用 Hub。
  • 选择 worker：优先选择第一方或广泛采用、近期发布的 worker，并使用广泛且高可用的 GPU 池。可通过 runpodctl hub list 观察以下信号：--owner runpod-workers（第一方）、--order-by releasedAt/updatedAt（近期发布）、--order-by deploys/stars（采用度）。不要为小模型指定它用不上的稀缺大型 GPU 层级。
• **“Active worker”指最小 worker 数，而不是最大 worker 数。**用户要求“active worker”时，指的是 --workers-min 1（始终预热一个 worker → 无冷启动），而不是 --workers-max 1（这只会限制上限）。预热的最小值为 1 的 worker 非常适合开发和迭代。
• ⚠️ 最小值为 1 的 worker 会持续计费，即使处于空闲状态也一样（这会使自动缩容至零失效）。开发时设置 --workers-min 1 后，完成时必须将其改回 --workers-min 0（或删除该端点），否则费用会在不知不觉中不断累积。
  • 需要 runpodctl ≥ v2.10.0。在更早的二进制版本中，--workers-min 0 和 --idle-timeout 0 会从更新请求中被静默丢弃（omitempty 吞掉了零值），因此重置看似已生效，但端点仍会继续计费。检查 runpodctl version；如果版本较旧，则用 serverless get <id> 确认，并改用 PATCH https://api.runpod.io/v2/serverless/<id>，显式传入 {"workers":{"min":0}}。
• serverless update 没有 --gpu-id 标志。要更改现有端点的 GPU 池，直接调用 PATCH https://api.runpod.io/v2/serverless/<id> 并传入 {"gpu":{"pools":["ADA_24"]}}（池 ID 来自 GET /v2/catalog/gpus 的 pool 字段）。不带 excludedTypes 发送 pools 会清除所有排除项。
• **CPU serverless 端点：**使用 runpodctl serverless create --compute-type CPU 创建，或调用 REST v2 POST https://api.runpod.io/v2/serverless，并用 cpu 块替代 gpu 块。绝不要向 REST v1 POST https://rest.runpod.io/v1/endpoints 发送 "computeType":"CPU"——它会静默创建 GPU 端点（下方 Serverless 命令部分有已核实的证据）。
• 用户已有模板 ID、需要可复用的镜像／配置默认值，或需要比 Hub 更底层的控制时，使用模板。
• 用户有特定 Docker 镜像且不需要保存模板时，使用 --image 直接创建 pod。
• 请求／响应推理 API 和可扩展 worker 使用 serverless；交互式工作、笔记本、训练、调试或长时间运行的会话使用 pod。
• 预处理、文件传输、轻量脚本和非 CUDA 工作使用 CPU pod。需要 CUDA、模型推理、训练或 GPU 内存时使用 GPU pod。
• **将 --cloud-type 保持为默认值 SECURE。**Community Cloud 的主机来自经过审核的供应商；Secure Cloud 的主机来自数据中心级别的提供商，因此通常更稳定。只有用户明确要求时才传入 --cloud-type COMMUNITY（在那里开放公共端口 22 需要机器拥有公共 IP，而 CLI 无法对此提出请求）。
• CPU pod 会在库存最多的 CPU 类型上分配 2 个 vCPU；如果未指定 --name，则默认使用不带标签的镜像名。CPU pod 可以使用网络卷（--network-volume-id），但不能使用 pod 卷（会拒绝 --volume-in-gb）。不要传入 GPU 标志。
• **每次创建 GPU 时都要设置 CUDA 下限：--min-cuda-version 12.8。**此选项适用于 pod create 和 serverless create（不适用于 template create），是防止现代镜像被调度到无法运行它的旧主机上的唯一保障——创建操作本身不会拒绝这种组合，但容器启动时会崩溃，或静默退回 CPU。只有在镜像基于 CUDA 13 构建时（runpod/comfyui:cuda13.0、cu1300 集群 PyTorch 镜像）才使用 13.0；CPU pod 或有意使用的旧镜像则省略此项。完整规则、allowedCudaVersions 精确匹配变体，以及检查可用容量的方法： runpod-usage GPU 选择“固定 CUDA 下限”。
• 等待资源可用：使用 --wait，不要自行编写轮询循环（v2.9.0+）。create 会在资源刚被调度后立即返回，因此标为“RUNNING”的 pod 常常无法通过 SSH 连接，而新建的端点会返回 404。pod create --wait 会在端口 22 响应 SSH banner 时返回；pod create --wait-for running（v2.15.0+）会在容器启动后返回，无需 SSH——当任务只需要容器启动时，或镜像不会启动 sshd 时（大多数 CPU 镜像都是如此，因为 CPU pod 没有 Runpod 管理的 SSH），使用此选项；否则普通的 --wait 会在整个超时时间内持续计费，最后再失败。如果 CPU 镜像会自行启动 sshd，普通的 --wait 仍然适用；用户需要 SSH 时应继续使用它。serverless create --wait 会在 /health 报告 worker 已就绪或正在运行时返回。超时或按下 ctrl-c 时，资源仍会保留，其 ID 位于错误对象的 id 字段中——读取该字段并清理，不要假设什么都没创建（pod 按秒计费；没有运行中 worker 的端点不会计费，但会在收到第一个请求时启动 worker）。
• 在 pod 上部署服务（Ollama、ComfyUI、开发服务器等）？尽可能在创建时声明其 --ports 和 --env；也可以通过 runpodctl pod update 修改现有 pod。然后按照 runpod-usage 技能中的 pod 开发流程（reference/pod-workflows.md）操作——通过 SSH 执行安装，将服务绑定到 0.0.0.0，并轮询代理 URL，直到收到响应。
• 如需 SSH，使用 runpodctl pod get <pod-id> 或 runpodctl ssh info <pod-id> 获取连接详情。runpodctl 没有交互式 shell 命令——ssh info 会返回连接命令和密钥，但不会建立连接。使用 ssh user@host "command" 自行通过 SSH 运行命令。
• 网络卷与位置有关。挂载卷前检查数据中心的可用性；迁移时使用 send / receive 或兼容 S3 的存储。
• 测试后清理付费资源：删除为验证而创建的 serverless 端点、pod 和临时卷。
  • **费用防护：**工作完成后移除 pod（runpodctl pod remove <pod-id>）。如需无人值守的截止时间，可在 pod 内安排停止操作：Runpod pod 自带 runpodctl 和 pod 专属 API 密钥（管理 Pod）。停止的 pod 仍会收取磁盘和任何卷的费用。
  • **--stop-after / --terminate-after 从未生效。**v2.12.0 之前的 runpodctl 虽然接受这两个 pod create 标志，但后端从未执行它们，因此 pod 会一直运行并在超过截止时间后继续计费。v2.12.0 已移除这两个标志。如果 runpodctl pod create --help 仍列出它们，请运行 runpodctl update。绝不要将它们作为费用防护方案。
  • **已挂载卷：**删除网络卷前，先移除正在使用该卷的 pod。

无服务器事实（背景信息，而非规则）

• 缩容至零计费： 无服务器端点会在 --workers-min 0（默认值）时缩容至零——空闲时不产生 GPU 费用，仅按请求秒数计费；这对请求/响应 API 来说是合理的成本策略。
• 镜像故障迹象： 如果已部署的工作器显示为 ready，但作业一直处于 IN_QUEUE 且 inProgress: 0，说明镜像有问题或分发异常——应切换到其他工作器，而不是继续等待。
• 诊断方法： 使用 runpodctl serverless health <endpoint-id>（v2.9.0+）读取工作器/作业数量，然后使用 runpodctl serverless logs <endpoint-id>（v2.10.0+）查看工作器实际输出的内容——无需手动编写 curl。若反复出现 system 的 "start container" 行，却没有 container 输出，说明容器在处理程序运行前就已退出。

命令

以下是必备命令。如需了解标志，请向二进制程序查询——使用 runpodctl <resource> <action> --help；它始终是最新的。reference/command-reference.md 介绍了 --help 无法说明的内容：标志成功时的含义、应以哪个字段为准，以及失败时的表现。

Pod

runpodctl pod list                                   # running pods (+ --all / --status / --since / --created-after)
runpodctl pod get <pod-id>                           # details incl. SSH info + runtimeStatus
runpodctl pod create --template-id <id> --gpu-id "NVIDIA GeForce RTX 4090" --min-cuda-version 12.8   # from template
runpodctl pod create --image <img> --gpu-id "NVIDIA GeForce RTX 4090" --min-cuda-version 12.8        # from image
runpodctl pod create --compute-type cpu --image ubuntu:22.04                 # CPU pod (2 vCPUs; name defaults to the image)
runpodctl pod create --image <img> --gpu-id <id> --wait                      # block until ssh answers, then print the pod (v2.9.0+)
runpodctl pod create --compute-type cpu --image ubuntu:22.04 --wait-for running  # block until the container is up; no sshd needed (v2.15.0+)
runpodctl pod {start|stop|restart|update|delete} <pod-id>                    # lifecycle (delete aliases: rm/remove; no reset in v3)
runpodctl pod logs <pod-id>                          # recent container+system logs, json lines (v2.10.0+)
runpodctl pod logs <pod-id> --follow                 # keep streaming, reconnects on its own
runpodctl pod logs <pod-id> --since 30m --source system   # platform view: image pull / create / start

runpodctl v3.0.0 移除了 pod reset。仅在确实需要重启时使用 pod restart。

部署卡住时会显示在 --source system 中（v2.10.0+）：拉取进度反复出现，或 create container 始终未进入 start。使用 --source container 查看工作负载自身的输出。每一行都是一个 {source,line,ts} 对象，因此可直接传给 jq。

判断 Pod 是否可用时应查看 runtimeStatus，而不是 desiredStatus（v2.9.0+）：镜像仍在拉取时，desiredStatus: RUNNING 也会显示为运行中。字段含义、原因标记以及两个边界情况（--status 仅筛选 desiredStatus；unknown 表示查询失败，而非 Pod 已停止）→ reference/command-reference.md。

Hub

浏览/搜索 Runpod Hub 中已有的条目。使用路由器能力矩阵选择执行路径。

如需编写项目的 Hub 条目文件，请使用 runpod-build-template。

runpodctl hub search vllm                            # find a repo (+ hub list [--type/--category/--order-by/--owner])
runpodctl hub get <listing-id|owner/name>            # repo details

无服务器（别名：sls）

runpodctl serverless list | get <endpoint-id> | delete <endpoint-id>
runpodctl serverless create --name "x" --template-id <id> --min-cuda-version 12.8   # from template
runpodctl serverless create --name "x" --hub-id <listing-id>    # from hub (+ --env KEY=VAL to override defaults)
runpodctl serverless create --hub-id <id> --gpu-id "NVIDIA GeForce RTX 4090" \
  --model-reference https://huggingface.co/<org>/<model>:main   # attach & host-cache a HF model (GPU only)
runpodctl serverless update <endpoint-id> --workers-max 5
runpodctl serverless create --template-id <id> --workers-min 1 --wait          # block until a worker is ready (v2.9.0+)

调用 URL 会随端点一并返回。 create/get/list/update 会包含一个 urls 对象（run、runsync、health），因此新建的端点无需再次查询即可调用——读取这些 URL，而不是自行拼接。它们基于 RUNPOD_INVOKE_URL（默认值为 https://api.runpod.ai/v2）生成；RUNPOD_API_URL/RUNPOD_GRAPHQL_URL 不会更改这些 URL：reference/output-and-errors.md。

读取工作器日志（v2.10.0+）——这也是一项一等功能，因此读取工作器输出不再需要通过 MCP 路径或手动构造 SSE 请求：

runpodctl serverless logs <endpoint-id>                       # every worker's recent logs, json lines
runpodctl serverless logs <endpoint-id> --worker <worker-id>  # just one worker
runpodctl serverless logs <endpoint-id> --follow              # picks up workers that scale up mid-follow
runpodctl serverless logs <endpoint-id> --since 1h --source system   # why a worker will not start

日志属于工作器，而非端点；因此，不使用 --worker 时会一次性读取所有日志，并为每行添加 workerId 标签。**崩溃循环迹象：**反复出现 system 的 "start container" 行，却没有 container 输出，说明容器在处理程序运行前就已退出——此时作业会滞留在队列中，问题并非容量不足。

调用端点（v2.9.0+）——提供一等命令，因此 Agent 无需手动构造 curl 请求或管理 bearer token：

runpodctl serverless run <endpoint-id> --input '{"prompt":"hello"}'   # submit and wait for the result
runpodctl serverless run <endpoint-id> --input-file payload.json      # same, payload from a file ("-" = stdin)
runpodctl serverless run <endpoint-id> --input '{}' --wait 15m        # longer budget (default 5m)
runpodctl serverless run <endpoint-id> --input '{}' --no-wait         # submit, print the queued job, exit 0
runpodctl serverless status <endpoint-id> <job-id>                    # check a job submitted earlier
runpodctl serverless health <endpoint-id>                             # worker + job counts

• 只传入处理程序负载——CLI 会自行将其封装为 {"input": <your json>}，因此粘贴完整的 curl 封装会导致重复封装。
• timeout 表示 CLI 停止等待，并不代表端点出故障。 如果消息中指出了 serverless status 命令，则作业仍在服务端运行——应轮询它，不要重新调用（否则会新建一个作业）。

关于负载规则、stdout/stderr 的区分、退出代码，以及为何从不使用 /runsync → reference/command-reference.md。 从 hub 创建： --hub-id 会解析 hub 列表项，提取构建镜像和配置（GPU ID、容器磁盘、环境变量），创建内联模板并进行部署。支持 SERVERLESS 和 POD 两种列表项类型。hub 配置中的 GPU ID 和环境变量默认值会自动包含；可使用 --gpu-id 和 --env 覆盖。

CPU 无服务器端点（始终/从不规则见上文的决策规则）：使用 runpodctl serverless create --compute-type CPU 创建（可选 --instance-id，例如 cpu3g-4-16）。已验证的证据说明为何不得使用 REST v1：2026-07-14，POST https://rest.runpod.io/v1/endpoints 携带 "computeType":"CPU" 后静默返回了 GPU 端点（gpuCount:1、cpuFlavorIds:null），而 runpodctl --compute-type CPU 正确返回了 computeType:"CPU" 和 instanceIds:["cpu3g-4-16"]。REST v2（POST https://api.runpod.io/v2/serverless）通过使用 cpu 块代替 gpu 来表示 CPU 端点。单独的运行时/调用 API https://api.runpod.ai/v2/<endpoint-id>/…（health/run/runsync/openai）属于另一个 v2，运行正常——此处 v1 与 v2 的注意事项仅针对控制/管理 REST。

模型缓存（--model-reference）：通过完整 URL 并指定 ref，将 Hugging Face 模型附加到端点，例如 https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main。Runpod 会在主机端将其缓存在标准 HF 缓存目录（/runpod-volume/huggingface-cache/hub/）中，因此 worker 可直接加载——无需烘焙，无需卷。可重复使用；支持 --template-id/--hub-id，仅限 GPU，要求 runpodctl v2.4.0+。完整机制及其与烘焙 / 网络卷 / Model Repository 的比较：reference/model-caching.md。端到端示例：黄金路径 20 — 模型缓存端点。

多区域 / 高可用（--network-volume-ids）：附加多个网络卷（每个数据中心一个），让 worker 分布在多个 DC，而不是固定在一个 DC—— runpodctl serverless create --template-id <t> --network-volume-ids <v1>,<v2> --data-center-ids <dc1>,<dc2> …。 要求 runpodctl ≥ v2.4.0（较旧版本不支持附加多个卷）。检查 runpodctl version；Homebrew tap 可能滞后，因此建议使用 GitHub releases 中的二进制文件。数据不会 在卷之间自动同步——参见黄金路径 10 — 多区域高可用无服务器。

如需查看准确的无服务器标志，请运行 runpodctl serverless <action> --help。

serverless update --model-reference 会在 JSON/YAML 输出中包含服务器解析的 modelReferences；--clear-models 会返回 modelReferences: []。其他更新不会获取模型引用；使用 serverless model-status <id> 查看。

模板（别名：tpl）

runpodctl template search <q>                        # find (+ template list [--type official/community/user, --all, --limit])
runpodctl template get <template-id>                 # details (README, env, ports)
runpodctl template create --name "x" --image "img" [--serverless]
runpodctl template delete <template-id>

网络卷（别名：nv）

runpodctl network-volume list                         # List all volumes
runpodctl network-volume get <volume-id>              # Get volume details
runpodctl network-volume create --name "x" --size 100 --data-center-id "US-GA-1"  # Create volume
runpodctl network-volume update <volume-id> --name "new"  # Update volume
runpodctl network-volume delete <volume-id>           # Delete volume

如需查看准确的网络卷标志，请运行 runpodctl network-volume <action> --help。

没有存储层级标志。 create 会配置数据中心的默认层级——没有 --type。若要创建高性能卷，请使用控制台（⚡ 数据中心的切换选项）或原始 v2 REST 调用（使用 "type":"HIGH_PERFORMANCE" 的 POST https://v2-rest.runpod.io/v2/network-volumes）——也可以使用 MCP create-network-volume 工具，该工具接受 volumeType（STANDARD | HIGH_PERFORMANCE）。创建后无法更改层级。启动详情：黄金路径 21。

模型（模型仓库）

runpodctl model 用于管理 Runpod 模型仓库——用于存储你自己的模型制品的托管式版本化存储（上传一次，即可分发给各个工作节点；不像网络卷那样固定在某个数据中心）。关于它是什么、为什么使用、如何使用、如何迁移出内置模型，以及模型仓库与卷的对比，请参阅：reference/model-caching.md。

runpodctl model list                                  # List your models
runpodctl model list --all                            # List all models (not just yours)
runpodctl model list --name "llama"                   # Filter by name
runpodctl model list --provider "meta"                # Filter by provider
runpodctl model add --name "my-model" --model-path ./model   # Upload a local model dir (multipart)
runpodctl model remove --name "my-model" --owner <owner>     # Remove a model

model add 支持上传会话、版本控制、元数据和私有来源凭据——请参阅实时帮助 runpodctl model add --help。

信息与 SSH

runpodctl user                                       # account info + balance (alias: me)
runpodctl gpu list                                   # available GPUs + $/hr + per-DC stock (+ --include-unavailable)
runpodctl datacenter list                            # datacenters (alias: dc)
runpodctl ssh info <pod-id>                          # SSH connection details (command + key; NOT an interactive session)

gpu list 包含定价和部署位置数据——securePricePerHr / communityPricePerHr（如果该云不提供相应 GPU，则明确显示为 null）以及 dataCenterAvailability[] 明细。在需要将创建任务调度到特定数据中心时，应查看明细，而不只是顶层的 stockStatus（它只代表所有数据中心中的最佳状态）；并传入 --include-unavailable，因为默认列表会隐藏无库存的 GPU，也可能遗漏只在目标数据中心有库存的 GPU。价格为Pod 按需费率。数据结构、库存值词汇以及 "none" 与省略键的哨兵值说明，请参阅： reference/output-and-errors.md。

ssh info 提供连接详情，而非会话。如果无法使用交互式 SSH，请运行 ssh user@host "command"。注册表身份验证、billing 历史记录和 SSH 密钥管理（ssh add-key/remove-key）请参阅 reference/command-reference.md。ssh info 将主机密钥验证交由你根据其输出运行的 OpenSSH 客户端处理。主机密钥固定适用于已弃用的 exec python（v2.15.0+）和旧版 project SSH（v2.15.0 至 v3.0.1）；v2.14.0 及更早版本会在这些路径中禁用主机密钥检查。特定版本的适用范围，以及为什么 ssh forget 需要操作员确认，请参阅 reference/command-reference.md。

文件传输

runpodctl send <path>                                # prints a one-time code, then blocks until the receiver connects
runpodctl receive <code>                             # positional code (no --code flag)

加密／增量／压缩传输——请勿预先打包为 tar。关键注意事项：在流式传输时捕获 send 标准输出的第一行（验证码）（使用后台运行并通过 tee 记录）；每次 send 都会生成一个新的验证码；两端都必须以 0 退出。完整 Agent 流程（通过 ssh 推送到 Pod，再执行 receive）：reference/command-reference.md。

实用工具

runpodctl doctor                                      # Diagnose and fix CLI issues
runpodctl update                                      # Update CLI
runpodctl version                                     # Show version
runpodctl completion                                  # Auto-detect shell and install completion

URL

Pod URL

访问 Pod 上公开的端口：

https://<pod-id>-<port>.proxy.runpod.net

示例：https://abc123xyz-8888.proxy.runpod.net

Serverless URL

优先使用 runpodctl serverless run|status|health（见上文）——它们使用相同的 api，并处理身份验证、验证和有界轮询。对于命令未涵盖的场景，请使用原始 URL：流式传输、兼容 OpenAI 的路由，或供用户复制粘贴的 curl 命令。

https://api.runpod.ai/v2/<endpoint-id>/run        # Async request
https://api.runpod.ai/v2/<endpoint-id>/runsync    # Sync request
https://api.runpod.ai/v2/<endpoint-id>/health     # Health check
https://api.runpod.ai/v2/<endpoint-id>/status/<job-id>  # Job status

serverless create/get/list/update 已在 urls 对象中返回 run/runsync/health——优先使用这些值，而不是手动拼接，因为非默认的 RUNPOD_INVOKE_URL 会更改基础 URL。只有 status/<job-id> 需要手动构建。

源码与文档

• CLI 源码：https://github.com/runpod/runpodctl
• 发布版本（二进制文件）：https://github.com/runpod/runpodctl/releases
• 文档：https://docs.runpod.io/runpodctl/overview