runpod/runpodctl

runpodctl 的功能

runpodctl 是 RunPod 的命令行客户端，可让您启动和管理 GPU 支持的容器（称为 pods）以及无服务器推理端点。使用该工具，您可以在终端中创建、启动、停止、删除和检查这些资源，调用无服务器函数，并在机器之间传输文件。

适用人群

• 需要按需 GPU 机器进行训练或实验的 AI 研究人员 / 开发者
• 将推理模型作为无服务器端点部署，并希望快速测试或监控的 ML 工程师
• 需要以编程方式配置计算资源而无需编写 HTTP 调用的 自动化脚本 或 AI 代理

核心功能

领域	命令（名词-动词风格）	可执行操作
Pod 管理	runpodctl pod list/get/create/update/start/stop/delete	列出现有 GPU Pod，检查 Pod 详情，从 Docker 镜像启动新 Pod，更改其配置，控制其生命周期
无服务器端点	runpodctl serverless list/get/create/update/delete/run/status/health	管理“无服务器”推理服务，使用 JSON 负载调用，轮询作业状态，检查工作器健康状态
等待就绪	--wait（在 pod create 或 serverless create 中使用）	阻塞直到 Pod 的 SSH 可达或无服务器工作器报告 ready/running，避免手动轮询循环
文件传输	runpodctl send <file> / runpodctl receive <code>	使用无 API 密钥的点对点工具 croc 在机器之间传输文件
输出格式	`--output=json	yaml
错误处理	stderr 中一致的 JSON 错误对象，带有稳定 code 字段	脚本可以基于错误码（not_found, usage_error, wait_timeout 等）可靠分支，而非解析自由格式消息

典型工作流程（快速入门）

# 1️⃣ 一次性保存您的 RunPod API 密钥
runpodctl config --apiKey=YOUR_KEY

# 2️⃣ 列出当前 Pod
runpodctl pod list

# 3️⃣ 启动新的 GPU Pod（示例：A100 上的 PyTorch 镜像）
runpodctl pod create \
  --image=runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04 \
  --gpu-id=NVIDIA_A100

# 4️⃣ 使用完毕后停止并删除
runpodctl pod stop <pod_id>
runpodctl pod delete <pod_id>

相同模式也适用于无服务器端点，例如 runpodctl serverless run <id> --input '{"prompt":"hello"}'

安装选项

平台	命令
Linux/macOS（包括 WSL）	wget -qO- cli.runpod.net | sudo bash
macOS (Homebrew)	brew install runpod/runpodctl/runpodctl
Windows PowerShell	wget https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.exe -O runpodctl.exe
Conda / Mamba / Pixi	conda install -c conda-forge runpodctl（或 mamba、pixi global install）

对开发者重要的设计要点

• JSON 优先输出：每个成功命令默认将单个 JSON 对象输出到 stdout。这使得 CLI 易于被其他程序或 LLM 驱动的代理消费。
• stdout / stderr 分离：数据（Pod 信息、作业负载）输出到 stdout，进度消息和错误对象输出到 stderr。避免流混合。
• 稳定错误码：每个错误都包含小写的 code（如 not_found, rate_limited）。脚本应基于此字段分支，而非 HTTP 状态或自由格式文本。
• 等待语义：--wait 会阻塞直到资源可使用（Pod 可 SSH 连接，无服务器至少有一个就绪工作器）。超时可配置（--wait-timeout）。中断等待不会删除资源；CLI 返回资源 ID，以便稍后清理。
• 无隐藏同步端点：CLI 始终使用异步 /run API 并轮询 /status。避免了 /runsync 端点的陷阱（计费残留、结果保留时间短）。

可能不需要它的情况

如果您仅通过 Web UI 或高级 SDK 使用 RunPod，则安装 runpodctl 价值不大。它在需要轻量、可脚本化接口以用于 CI 流水线、远程 shell 或作为自主 AI 代理一部分时才真正发挥作用。

---

以上所有细节均直接来自项目 README；未推断任何额外功能。