runpodctl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runpodctl

Manage GPU pods, serverless endpoints, templates, volumes, and models.

管理GPU Pod、Serverless端点、模板、卷和模型。

Install

安装

curl -sSL https://cli.runpod.net | bash

(any platform) or

brew install runpod/runpodctl/runpodctl

. Manual binaries, Windows/Linux steps, and the version caveat (

--model-reference

+ multi-volume need v2.4.0+): reference/install.md.

Old runpodctl builds silently lack newer flags/behaviors (e.g.
--model-reference
doesn't exist before v2.4.0) and produce confusing downstream errors — and the Homebrew tap can lag well behind. So, before any work:
Update to the latest build — check
runpodctl version
, then run
runpodctl update
(or reinstall from the latest release).
Pin to one recent version for the whole task.

Never switch between an old and a new binary mid-task (that flip-flop is a known failure).
Verify once —
runpodctl version
shows the current build before you continue.

curl -sSL https://cli.runpod.net | bash

（支持任意平台）或

brew install runpod/runpodctl/runpodctl

。手动二进制包、Windows/Linux安装步骤，以及版本注意事项（

--model-reference

和多卷功能需要 v2.4.0+）：reference/install.md。

旧版本的runpodctl会默认缺失新特性/参数（例如
--model-reference
在v2.4.0之前不存在），并导致后续的混淆性错误——而且Homebrew源的版本可能会滞后于官方发布。因此，在开始工作前：
更新到最新版本——执行
runpodctl version
查看当前版本，然后运行
runpodctl update
（或从最新发布页重新安装）。
为整个任务固定使用一个近期版本。

切勿在任务中途切换新旧版本的二进制文件（这种来回切换是已知的故障诱因）。
验证版本——在继续操作前，通过
runpodctl version
确认当前使用的版本。

Quick start

快速开始

bash

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-v21 --gpu-id "NVIDIA GeForce RTX 4090"  # Create from template
runpodctl pod list                  # List your pods

Auth: an agent should
export RUNPOD_API_KEY=...
(non-interactive).
runpodctl doctor
is interactive (prompts) and also sets up SSH keys — good for a human's first run, not for scripted use.

API key: https://console.runpod.io/user/settings

bash

runpodctl update                    # 第一步：更新到最新版本——旧版本会引发混淆性错误
runpodctl version                   # 在执行任何操作前确认当前版本
export RUNPOD_API_KEY=your_key      # 非交互式认证（适用于Agent）——runpodctl会读取该环境变量
runpodctl doctor                    # 交互式首次设置（API密钥 + SSH）——适用于人工操作
runpodctl --help                    # 查看当前顶级命令
runpodctl pod create --help         # 在创建Pod前查看具体的可用参数
runpodctl gpu list                  # 查看可用的GPU类型
runpodctl datacenter list           # 查看各数据中心的GPU可用性（用于协同部署GPU和卷）
runpodctl hub search vllm           # 查找Hub仓库
runpodctl serverless create --hub-id <id> --name "my-vllm"  # 从Hub部署
runpodctl template search pytorch   # 查找模板
runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA GeForce RTX 4090"  # 从模板创建Pod
runpodctl pod list                  # 列出你的所有Pod

认证方式：Agent应使用
export RUNPOD_API_KEY=...
（非交互式）。
runpodctl doctor
是交互式的（会弹出提示），同时也会配置SSH密钥——适合人工首次使用，不适合脚本场景。

API密钥获取地址：https://console.runpod.io/user/settings

Live Help Is Authoritative

实时帮助为权威参考

Live

runpodctl --help

output is authoritative for exact flags, aliases, and command syntax. Use this skill for workflows, decision rules, safety notes, and common examples.

bash

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

Before using unfamiliar commands, inspect live help first. Do not rely on this skill as an exhaustive flag reference.

What live help does not cover: output shapes, error codes, and exit-code behavior.

--help

lists flags; it never shows you what a failure looks like. For those, use reference/output-and-errors.md — and when in doubt, probe the binary: run the command wrong on purpose (

runpodctl serverless get nope

) and read the JSON it emits. Every doc is a snapshot, this skill included; the binary in front of you wins.

runpodctl --help

的实时输出是参数、别名和命令语法的权威参考。本文档仅用于提供工作流、决策规则、注意事项和常见示例。

bash

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

在使用不熟悉的命令前，请先查看实时帮助。不要依赖本文档作为详尽的参数参考。

实时帮助未覆盖的内容：输出格式、错误代码和退出码行为。

--help

仅列出参数；不会展示错误场景。如需了解这些内容，请查看reference/output-and-errors.md——如有疑问，直接测试二进制文件：故意执行错误命令（如

runpodctl serverless get nope

）并读取其输出的JSON。所有文档都是快照，包括本内容；你当前使用的二进制文件才是最终依据。

Output & errors

输出与错误

Data is JSON on stdout (

--output=yaml

is the only alternative — there is no table format; anything else silently returns JSON). A failure from the resource commands is a single flat JSON object on stderr plus a non-zero exit:

jsonc

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

Branch on
code
, never on
status
or the message.

status

is there only when the failure arrived on a non-2xx response — GraphQL reports a missing resource as HTTP 200 + null data, so

if status == 404

misses every GraphQL not-found.

`code`	what to do
`network_error`	retry with backoff — the only code meaning "couldn't reach the API"
`rate_limited` `server_error`	retry with backoff — 429/5xx from the API
`usage_error` `cli_error` `bad_request` `not_found` `conflict`	don't retry, fix the input
`no_credentials`	no key set: `export RUNPOD_API_KEY=…` or `runpodctl doctor`
`unauthorized` `forbidden`	a key is set but is wrong/expired or lacks access — don't retry, don't re-prompt for a missing key
anything else	treat as fatal, surface `error` verbatim — the API can pass through its own code

runpodctl never retries internally; nothing backs off for you.

not_found
always means the API lacks the resource, never a mistyped local path (that's
```
cli_error
```
).
cli_error
is a mixed bucket: local environment problems and invocation mistakes the command validates itself (e.g.
```
ssh remove-key
```
with neither
```
--name
```
nor
```
--fingerprint
```
). Only cobra-enforced required flags are
```
usage_error
```
.
usage_error
= unknown command/flag, bad args, missing cobra-required flag; usage text follows the JSON. Runtime errors no longer print usage.
Non-empty stderr does not mean failure — deprecation
```
warning:
```
and
```
note:
```
lines go to stderr on success too. Gate on the exit code, then parse stderr.

Coded errors, the serverless

urls

object and GPU pricing all need runpodctl ≥ v2.8.0. Older binaries emit

{"error":"…"}

with no
code
and no
status
— still JSON-shaped, so a

switch (err.code)

silently gets

undefined

rather than failing loudly. Gate on
code
being present, not on JSON-vs-plaintext;

runpodctl version

is unreliable for this (plaintext, and a source build reports a placeholder version).

Full code table, the surfaces that still print plaintext (

exec

, legacy

pod

commands,

project

), and the env-var table (incl.

RUNPOD_INVOKE_URL

): reference/output-and-errors.md.

数据通过标准输出(stdout)以JSON格式返回（唯一的替代格式是

--output=yaml

；不支持表格格式；其他格式默认返回JSON）。资源命令执行失败时，会在标准错误(stderr)输出单个扁平化JSON对象，并返回非零退出码：

jsonc

{"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强制要求的参数；错误信息后会跟随使用说明。运行时错误不再打印使用说明。
非空stderr不代表执行失败——成功执行时，弃用警告
```
warning:
```
和提示
```
note:
```
也会输出到stderr。应根据退出码判断是否失败，再解析stderr内容。

错误码、Serverless的

urls

对象以及GPU定价功能都需要 runpodctl ≥ v2.8.0。旧版本的二进制文件会输出

{"error":"…"}

，但没有
code
和
status
字段——仍然是JSON格式，因此

switch (err.code)

会静默获取

undefined

而非报错。应先判断
code
字段是否存在，而非判断是否为JSON格式；

runpodctl version

的输出不可靠（纯文本，源码构建版本会显示占位符版本）。

完整的错误码表、仍会输出纯文本的场景（

exec

、旧版

pod

命令、

project

），以及环境变量表（包括

RUNPOD_INVOKE_URL

）：reference/output-and-errors.md。

Decision Rules

决策规则

Use Hub when the user wants a known deployable app or worker such as vLLM, ComfyUI, Whisper, or a Runpod-maintained repo.
- Picking a worker: prefer a first-party or well-adopted, recently-released worker on a broad, high-availability GPU pool. Observable signals via
```
runpodctl hub list
```
  :
```
--owner runpod-workers
```
  (first-party),
```
--order-by releasedAt
```
  /
```
updatedAt
```
  (recency),
```
--order-by deploys
```
  /
```
stars
```
  (adoption). Don't pin a scarce large-GPU tier a small model doesn't need.
"Active worker" = minimum workers, not maximum. If a user asks for an "active worker," they mean
```
--workers-min 1
```
(keep one worker always warm → no cold start), not
```
--workers-max 1
```
(that only caps the ceiling). A warm min-1 worker is ideal for development/iteration.
⚠️ A min-1 worker bills continuously, even while idle (it defeats scale-to-zero). When you set
```
--workers-min 1
```
for dev, you must set it back to
```
--workers-min 0
```
(or delete the endpoint) when done — otherwise it quietly runs up cost.

serverless update

has no
--gpu-id
flag. To change an existing endpoint's GPU pool, call

PATCH https://rest.runpod.io/v1/endpoints/<id>

with

{"gpuTypeIds":[...]}

directly.

CPU serverless endpoints: always create them with
```
runpodctl serverless create --compute-type CPU
```
— not the MCP server, whose v2
```
create-endpoint
```
requires
```
gpuPoolIds
```
and has no CPU concept. Never use the public control REST
```
POST https://rest.runpod.io/v1/endpoints
```
with
```
"computeType":"CPU"
```
— it silently provisions a GPU endpoint instead (verified evidence in the Serverless command section below).
Use templates when the user already has a template ID, wants reusable image/config defaults, or needs lower-level control than Hub.
Use direct pod creation with
```
--image
```
when the user has a specific Docker image and does not need a saved template.
Use serverless for request/response inference APIs and scalable workers; use pods for interactive work, notebooks, training, debugging, or long-lived sessions.
Use CPU pods for preprocessing, file movement, lightweight scripts, and non-CUDA work. Use GPU pods when CUDA, model inference, training, or GPU memory is required.
Do not pass GPU flags when creating CPU pods. Check
```
runpodctl pod create --help
```
for the current valid flag set.
Standing up a service on a pod (Ollama, ComfyUI, a dev server)? Declare its
```
--ports
```
and
```
--env
```
at creation (they can't be added to a running pod without a reset), then follow the pod development loop in the
```
runpod-usage
```
skill (
```
reference/pod-workflows.md
```
) — SSH-exec the install, bind to
```
0.0.0.0
```
, and poll the proxy URL until it answers.
For SSH, use
```
runpodctl pod get <pod-id>
```
or
```
runpodctl ssh info <pod-id>
```
to retrieve connection details. runpodctl has no interactive-shell command —
```
ssh info
```
returns the connection command + key but does not connect. Run commands over SSH yourself with
```
ssh user@host "command"
```
.
Network volumes are location-sensitive. Check datacenter availability before attaching volumes, and use
```
send
```
/
```
receive
```
or S3-compatible storage for migrations.
Clean up paid resources after tests: delete serverless endpoints, pods, and temporary volumes created for validation.
- Cost guard on creation: use
```
--terminate-after
```
  (deletes the pod);
```
--stop-after
```
  only stops it, so disk/volume keep billing.
- Attached volume: to delete a network volume, remove the pod using it first.

当用户需要部署已知的可运行应用或工作负载（如vLLM、ComfyUI、Whisper，或Runpod官方维护的仓库）时，使用Hub。
- 选择工作负载：优先选择Runpod官方或广泛采用、近期发布的工作负载，且部署在覆盖范围广、高可用性的GPU池上。可通过
```
runpodctl hub list
```
  查看可观测指标：
```
--owner runpod-workers
```
  （官方）、
```
--order-by releasedAt
```
  /
```
updatedAt
```
  （发布/更新时间）、
```
--order-by deploys
```
  /
```
stars
```
  （部署量/星标数）。不要为小型模型选择稀缺的大显存GPU规格。
"活跃工作负载"指最小工作负载数，而非最大。如果用户要求"活跃工作负载"，他们的意思是
```
--workers-min 1
```
（始终保持一个工作负载处于预热状态→无冷启动），而非
```
--workers-max 1
```
（仅限制最大工作负载数）。预热的最小1个工作负载非常适合开发/迭代场景。
⚠️ 设置最小工作负载数为1时，即使空闲也会持续计费（这会取消自动缩容至零的功能）。当你为开发场景设置
```
--workers-min 1
```
后，必须在完成后将其改回
```
--workers-min 0
```
（或删除端点）——否则会悄悄产生高额费用。

serverless update

没有
--gpu-id
参数。如需修改现有端点的GPU池，请直接调用

PATCH https://rest.runpod.io/v1/endpoints/<id>

，请求体为

{"gpuTypeIds":[...]}

。

CPU Serverless端点：必须使用
```
runpodctl serverless create --compute-type CPU
```
创建——不要使用MCP服务器，其v2版本的
```
create-endpoint
```
要求
```
gpuPoolIds
```
，且不支持CPU类型。切勿使用公开的控制层REST接口
```
POST https://rest.runpod.io/v1/endpoints
```
并设置
```
"computeType":"CPU"
```
——它会静默创建GPU端点（下方Serverless命令部分有验证证据）。
当用户已有模板ID、需要可复用的镜像/配置默认值，或需要比Hub更底层的控制时，使用模板。
当用户有特定的Docker镜像且不需要保存模板时，使用
```
--image
```
参数直接创建Pod。
Serverless适用于请求/响应式推理API和可扩展工作负载；Pod适用于交互式工作、笔记本、训练、调试或长期会话。
CPU Pod适用于预处理、文件传输、轻量级脚本和非CUDA工作。GPU Pod适用于CUDA任务、模型推理、训练或需要GPU显存的场景。
创建CPU Pod时不要传递GPU相关参数。请查看
```
runpodctl pod create --help
```
获取当前有效的参数集合。
在Pod上部署服务（如Ollama、ComfyUI、开发服务器）？请在创建时声明
```
--ports
```
和
```
--env
```
参数（运行中的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和临时卷。
- 创建时的成本防护：使用
```
--terminate-after
```
  参数（会删除Pod）；
```
--stop-after
```
  仅会停止Pod，因此磁盘/卷仍会产生费用。
- 挂载的卷：要删除网络卷，请先删除使用该卷的Pod。

Serverless facts (context, not rules)

Serverless相关事实（背景信息，非规则）

Scale-to-zero billing: serverless endpoints scale to zero with
```
--workers-min 0
```
(the default) — no GPU billing while idle, only per request-second; this is the right cost posture for a request/response API.
Broken-image tell: if deployed workers go
```
ready
```
but jobs sit
```
IN_QUEUE
```
with
```
inProgress: 0
```
, the image is broken/mis-dispatching — the fix is to switch to a different worker rather than wait it out.
Diagnosing it: there's no first-class serverless worker-log command, so diagnosis relies on
```
/health
```
worker counts.

缩容至零计费：当设置
```
--workers-min 0
```
（默认值）时，Serverless端点会自动缩容至零——空闲时不会产生GPU费用，仅按请求秒数计费；这是请求/响应式API的理想成本策略。
镜像损坏的迹象：如果部署的工作负载显示
```
ready
```
但任务处于
```
IN_QUEUE
```
状态且
```
inProgress: 0
```
，则说明镜像损坏/调度错误——解决方法是切换到其他工作负载，而非等待。
诊断方法：没有专门的Serverless工作负载日志命令，因此诊断依赖于
```
/health
```
接口返回的工作负载数量。

Commands

命令

Essentials below. Full flag menu → reference/command-reference.md (pods lifecycle, hub/template filters, registry auth, billing, SSH key management); live

runpodctl <resource> <action> --help

is authoritative for exact flags.

以下是核心命令。完整参数列表 → reference/command-reference.md（Pod生命周期、Hub/模板筛选、镜像仓库认证、账单、SSH密钥管理）；

runpodctl <resource> <action> --help

的实时输出是参数的权威参考。

Pods

bash

runpodctl pod list                                   # running pods (+ --all / --status / --since / --created-after)
runpodctl pod get <pod-id>                           # details incl. SSH info
runpodctl pod create --template-id <id> --gpu-id "NVIDIA GeForce RTX 4090"   # from template
runpodctl pod create --image <img> --gpu-id "NVIDIA GeForce RTX 4090"        # from image
runpodctl pod create --compute-type cpu --image ubuntu:22.04                 # CPU pod (lowercase `cpu`; serverless uses `CPU`)
runpodctl pod {start|stop|restart|reset|update|delete} <pod-id>              # lifecycle (delete aliases: rm/remove)

bash

runpodctl pod list                                   # 列出运行中的Pod（支持--all / --status / --since / --created-after参数）
runpodctl pod get <pod-id>                           # 获取Pod详情，包括SSH信息
runpodctl pod create --template-id <id> --gpu-id "NVIDIA GeForce RTX 4090"   # 从模板创建Pod
runpodctl pod create --image <img> --gpu-id "NVIDIA GeForce RTX 4090"        # 从镜像创建Pod
runpodctl pod create --compute-type cpu --image ubuntu:22.04                 # 创建CPU Pod（注意是小写`cpu`；Serverless使用`CPU`）
runpodctl pod {start|stop|restart|reset|update|delete} <pod-id>              # Pod生命周期管理（delete的别名：rm/remove）

Hub

Browse/search the Runpod Hub (curated deployable repos).

bash

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

浏览/搜索Runpod Hub（精选的可部署仓库）。

bash

runpodctl hub search vllm                            # 查找仓库（支持hub list [--type/--category/--order-by/--owner]参数）
runpodctl hub get <listing-id|owner/name>            # 获取仓库详情

Serverless (alias: sls)

Serverless（别名：sls）

bash

runpodctl serverless list | get <endpoint-id> | delete <endpoint-id>
runpodctl serverless create --name "x" --template-id <id>       # 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

Invoke URLs come back with the endpoint.

create

get

list

update

include a

urls

object (

run

runsync

health

), so a freshly created endpoint is callable without a second lookup — read them instead of assembling the URL yourself. They're built from

RUNPOD_INVOKE_URL

(default

https://api.runpod.ai/v2

), which

RUNPOD_API_URL

RUNPOD_GRAPHQL_URL

do not move: reference/output-and-errors.md.

Create from hub:

--hub-id

resolves the hub listing, extracts the build image and config (GPU IDs, container disk, env vars), creates an inline template, and deploys. Accepts both SERVERLESS and POD listing types. GPU IDs and env var defaults from the hub config are included automatically; override with

--gpu-id

and

--env

CPU serverless endpoints (the always/never rule is in Decision Rules above): create with

runpodctl serverless create --compute-type CPU

(optionally

--instance-id

, e.g.

cpu3g-4-16

). Verified evidence for why the public REST must not be used: 2026-07-14,

POST https://rest.runpod.io/v1/endpoints

with

"computeType":"CPU"

silently returned a GPU endpoint (

gpuCount:1

cpuFlavorIds:null

), while

runpodctl --compute-type CPU

correctly returned

computeType:"CPU"

with

instanceIds:["cpu3g-4-16"]

. The MCP server is not an alternative here: its v2

create-endpoint

requires

gpuPoolIds

and the v2 spec has no

computeType

cpuFlavor

field at all (verified 2026-07-29). The public control REST is v1-only (

rest.runpod.io/v2

just redirects to docs). The separate runtime/invoke API

https://api.runpod.ai/v2/<endpoint-id>/…

(health/run/runsync/openai) is a different v2 and works fine — the v1-vs-v2 caveat here is only about the control/management REST.

Model cache (
--model-reference
): Attach a Hugging Face model to the endpoint by full URL with a ref, e.g.

https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main

. Runpod caches it host-side in the standard HF cache dir (

/runpod-volume/huggingface-cache/hub/

), so the worker loads it directly — no bake, no volume. Repeatable; works with

--template-id

--hub-id

, GPU only, runpodctl v2.4.0+. Full mechanics + how it compares to baking / network volume / the Model Repository: reference/model-caching.md. Worked end-to-end: golden path 20 — model-caching endpoint.

Multi-region / high-availability (
--network-volume-ids
): attach multiple network volumes (one per data center) so workers spread across DCs instead of being pinned to one —

runpodctl serverless create --template-id <t> --network-volume-ids <v1>,<v2> --data-center-ids <dc1>,<dc2> …

. Requires runpodctl ≥ v2.4.0 (older versions don't support multi-volume attach). Check

runpodctl version

; the Homebrew tap can lag, so prefer the GitHub releases binary. Data does not sync between volumes automatically — see golden path 10 — multi-region HA serverless.

For exact serverless flags, run

runpodctl serverless <action> --help

bash

runpodctl serverless list | get <endpoint-id> | delete <endpoint-id>
runpodctl serverless create --name "x" --template-id <id>       # 从模板创建端点
runpodctl serverless create --name "x" --hub-id <listing-id>    # 从Hub创建端点（支持--env KEY=VAL参数覆盖默认值）
runpodctl serverless create --hub-id <id> --gpu-id "NVIDIA GeForce RTX 4090" \
  --model-reference https://huggingface.co/<org>/<model>:main   # 挂载并缓存Hugging Face模型（仅支持GPU，需runpodctl v2.4.0+）
runpodctl serverless update <endpoint-id> --workers-max 5

调用URL会随端点信息返回。

create

get

list

update

命令的返回结果中包含

urls

对象（

run

、

runsync

、

health

），因此新创建的端点无需再次查询即可调用——请直接使用这些URL，而非手动拼接。这些URL基于

RUNPOD_INVOKE_URL

构建（默认值为

https://api.runpod.ai/v2

），而

RUNPOD_API_URL

RUNPOD_GRAPHQL_URL

不会改变该值：reference/output-and-errors.md。

从Hub创建：

--hub-id

会解析Hub列表，提取构建镜像和配置（GPU ID、容器磁盘、环境变量），创建内联模板并部署。支持SERVERLESS和POD两种列表类型。Hub配置中的GPU ID和环境变量默认值会自动包含；可通过

--gpu-id

和

--env

参数覆盖。

CPU Serverless端点（决策规则中的必选/禁用规则）：使用

runpodctl serverless create --compute-type CPU

创建（可选

--instance-id

，例如

cpu3g-4-16

）。禁止使用公开REST接口的验证证据：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"]

。MCP服务器不是替代方案：其v2版本的

create-endpoint

要求

gpuPoolIds

，且v2规范中完全没有

computeType

cpuFlavor

字段（2026-07-29验证）。公开的控制层REST接口仅支持v1版本（

rest.runpod.io/v2

会重定向到文档）。独立的运行时/调用API

https://api.runpod.ai/v2/<endpoint-id>/…

（health/run/runsync/openai）是不同的v2版本，可正常使用——此处的v1-vs-v2注意事项仅针对控制/管理层REST接口。

模型缓存（
--model-reference
）：通过完整URL加引用挂载Hugging Face模型，例如

https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main

。Runpod会在主机侧的标准HF缓存目录（

/runpod-volume/huggingface-cache/hub/

）中缓存模型，因此工作负载可直接加载——无需打包镜像，无需卷存储。该功能可重复使用；支持与

--template-id

--hub-id

配合使用，仅支持GPU，需runpodctl v2.4.0+。完整机制以及与镜像打包/网络卷/模型仓库的对比：reference/model-caching.md。端到端验证路径：20 — 模型缓存端点。

多区域/高可用性（
--network-volume-ids
）：挂载多个网络卷（每个数据中心一个），使工作负载分布在多个数据中心而非固定在一个——

runpodctl serverless create --template-id <t> --network-volume-ids <v1>,<v2> --data-center-ids <dc1>,<dc2> …

。需runpodctl ≥ v2.4.0（旧版本不支持多卷挂载）。请检查

runpodctl version

；Homebrew源可能滞后，建议使用GitHub发布页的二进制文件。卷之间不会自动同步数据——请查看验证路径10 — 多区域高可用Serverless。

如需查看Serverless的具体参数，请运行

runpodctl serverless <action> --help

。

Templates (alias: tpl)

Templates（别名：tpl）

bash

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>

bash

runpodctl template search <q>                        # 查找模板（支持template list [--type official/community/user, --all, --limit]参数）
runpodctl template get <template-id>                 # 获取模板详情（README、环境变量、端口）
runpodctl template create --name "x" --image "img" [--serverless]
runpodctl template delete <template-id>

Network Volumes (alias: nv)

Network Volumes（别名：nv）

bash

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

For exact network volume flags, run

runpodctl network-volume <action> --help

No storage-tier flag.
create
provisions the data center's default tier — there's no
--type
. To get a High-Performance volume, use the console (a ⚡ data center's toggle) or a raw v2 REST call (
POST https://v2-rest.runpod.io/v2/network-volumes
with
"type":"HIGH_PERFORMANCE"
) — or the MCP
create-network-volume
tool, which takes
volumeType
(
STANDARD
|
HIGH_PERFORMANCE
). Tier is immutable after creation. Launch details: golden path 21.

bash

runpodctl network-volume list                         # 列出所有卷
runpodctl network-volume get <volume-id>              # 获取卷详情
runpodctl network-volume create --name "x" --size 100 --data-center-id "US-GA-1"  # 创建卷
runpodctl network-volume update <volume-id> --name "new"  # 更新卷名称
runpodctl network-volume delete <volume-id>           # 删除卷

如需查看Network Volumes的具体参数，请运行

runpodctl network-volume <action> --help

。

无存储层级参数。
create
命令会创建数据中心的默认层级卷——没有
--type
参数。如需创建高性能卷，请使用控制台（带⚡标识的数据中心的切换按钮）或直接调用v2 REST接口（
POST https://v2-rest.runpod.io/v2/network-volumes
，请求体设置
"type":"HIGH_PERFORMANCE"
）——或使用MCP的
create-network-volume
工具，该工具支持
volumeType
参数（
STANDARD
|
HIGH_PERFORMANCE
）。卷的层级创建后不可修改。发布详情：验证路径21。

Models (Model Repository)

Models（模型仓库）

runpodctl model

manages the Runpod Model Repository — managed, versioned storage for your own model artifacts (upload once, distributed to workers; not pinned to a data center like a network volume). What it is, why/how, migrating off a baked-in model, and Model-Repo-vs-volume: reference/model-caching.md.

bash

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

supports upload sessions, versioning, metadata, and private-source credentials — see live

runpodctl model add --help

runpodctl model

用于管理Runpod模型仓库——为你自己的模型制品提供托管、版本化存储（上传一次，分发到所有工作负载；不像网络卷那样绑定到特定数据中心）。模型仓库的定义、使用原因/方式、从镜像打包模型迁移的方法，以及模型仓库与卷的对比：reference/model-caching.md。

bash

runpodctl model list                                  # 列出你的所有模型
runpodctl model list --all                            # 列出所有模型（不限于你自己的）
runpodctl model list --name "llama"                   # 按名称筛选
runpodctl model list --provider "meta"                # 按提供商筛选
runpodctl model add --name "my-model" --model-path ./model   # 上传本地模型目录（分块上传）
runpodctl model remove --name "my-model" --owner <owner>     # 删除模型

model add

支持上传会话、版本控制、元数据和私有源凭证——请查看

runpodctl model add --help

的实时输出。

Info & SSH

信息与SSH

bash

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
carries pricing and placement data —

securePricePerHr

communityPricePerHr

(explicitly

null

when that cloud doesn't offer the GPU) and a

dataCenterAvailability[]

breakdown. Read the breakdown, not just top-level

stockStatus

(which is only the best status across DCs), when a create has to schedule in a specific DC — and pass

--include-unavailable

, since the default listing hides no-stock GPUs and can omit one that has stock only in the DC you want. The prices are pod on-demand rates. Shape, stock-value vocabulary and the

"none"

vs omitted-key sentinel: reference/output-and-errors.md.

ssh info

gives connection details, not a session — if interactive SSH isn't available, run

ssh user@host "command"

. Registry auth,
billing
history, and SSH key management (

ssh add-key

remove-key

) are in reference/command-reference.md.

bash

runpodctl user                                       # 账户信息 + 余额（别名：me）
runpodctl gpu list                                   # 可用GPU列表 + 每小时价格 + 各数据中心库存（支持--include-unavailable参数）
runpodctl datacenter list                            # 数据中心列表（别名：dc）
runpodctl ssh info <pod-id>                          # SSH连接详情（命令 + 密钥；不是交互式会话）

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。

File Transfer

文件传输

bash

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

Encrypted/incremental/compressed — don't pre-tar. Key gotchas: capture the first line of
send
stdout (the code) as it streams (background + tee), each

send

mints a fresh code, both sides must exit

. Full agent flow (pod push via

ssh

receive

): reference/command-reference.md.

bash

runpodctl send <path>                                # 生成一次性代码，然后阻塞直到接收方连接
runpodctl receive <code>                             # 传入代码作为位置参数（无需--code参数）

支持加密/增量传输/压缩——无需预先打包成tar。关键注意事项：捕获

send

输出的第一行（代码）（可通过后台运行+tee命令实现），每次

send

都会生成新的代码，双方必须正常退出（退出码为0）。完整的Agent流程（通过

ssh

receive

推送Pod文件）：reference/command-reference.md。

Utilities

实用工具

bash

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

bash

runpodctl doctor                                      # 诊断并修复CLI问题
runpodctl update                                      # 更新CLI
runpodctl version                                     # 显示版本
runpodctl completion                                  # 自动检测shell并安装自动补全

URLs

URL

Pod URLs

Pod URL

Access exposed ports on your pod:

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

Example:

https://abc123xyz-8888.proxy.runpod.net

访问Pod上暴露的端口：

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

示例：

https://abc123xyz-8888.proxy.runpod.net

Serverless URLs

Serverless URL

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

already return

run

runsync

health

in a

urls

object — prefer those over hand-assembling, since a non-default

RUNPOD_INVOKE_URL

changes the base. Only

status/<job-id>

has to be built by hand.

https://api.runpod.ai/v2/<endpoint-id>/run        # 异步请求
https://api.runpod.ai/v2/<endpoint-id>/runsync    # 同步请求
https://api.runpod.ai/v2/<endpoint-id>/health     # 健康检查
https://api.runpod.ai/v2/<endpoint-id>/status/<job-id>  # 任务状态

serverless create

get

list

update

命令的返回结果中已包含

run

runsync

health

的URL——优先使用这些URL，而非手动拼接，因为非默认的

RUNPOD_INVOKE_URL

会改变基础地址。只有

status/<job-id>

需要手动拼接。

Source & docs

源码与文档

CLI source: https://github.com/runpod/runpodctl
Releases (binaries): https://github.com/runpod/runpodctl/releases
Docs: https://docs.runpod.io/runpodctl/overview

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