runpod/runpodctl

runpodctl – Runpod GPU 资源的命令行工具

是什么 – runpodctl 是一个与 Runpod 平台（runpod.io）通信的命令行客户端。它允许您创建、列出、启动、停止和删除 GPU 加速的 Pod，以及管理服务器无服务的“端点”（在 Runpod 基础设施上运行的函数）。所有繁重的工作（API 调用、认证、日志流式传输）都隐藏在简单的命令背后。

为何使用它 – 当您需要按需 GPU 计算资源用于训练、推理或其他 AI 工作负载时，Runpod 提供了云机器。runpodctl 为您提供了一种快速、可脚本化的途径来启动这些机器，检查日志、传输文件，并调用无服务器函数，而无需编写原始 HTTP 请求。

安装方式 – 该工具可通过多种方式安装：

• Linux/macOS（含 WSL）的一行脚本：wget -qO- cli.runpod.net | sudo bash
• macOS 上的 Homebrew：brew install runpod/runpodctl/runpodctl
• Windows PowerShell 脚本：下载 zip 文件，解压到 %LOCALAPPDATA%\runpodctl，并添加到 PATH。
• Conda-forge（conda, mamba, pixi）：conda install conda-forge::runpodctl（或等效的 mamba/pixi 命令）。

基本工作流程

# 设置 API 密钥（只需一次）
runpodctl config --apiKey=YOUR_KEY

# 查看已有资源
runpodctl pod list
runpodctl pod get POD_ID

# 启动新的 GPU Pod
runpodctl pod create \
  --image=runpod/pytorch:2.8.0-py3.11-cuda12.8.1-cudnn-devel-ubuntu22.04 \
  --gpu-id=NVIDIA_A100

# 控制其生命周期
runpodctl pod start POD_ID
runpodctl pod stop POD_ID
runpodctl pod delete POD_ID

无服务器端点 – 无服务器产品也有类似的命令：

• runpodctl serverless list / create / update / delete
• runpodctl serverless run ID --input '{"prompt":"hello"}' 可调用函数并等待结果。
• 日志流式传输（runpodctl serverless logs ID）与 Pod 日志相同，输出 JSON-行格式，可被 jq 等工具管道处理。

日志处理 – Pod 和端点日志均以 JSON-行格式（{source,line,ts}）从独立 API 端点流式传输，支持可选标志：

• --tail N – 显示每个来源的最后 N 行。
• --follow – 保持流式连接打开。
• --since <duration> – 按时间过滤。
• --source system|container – 选择平台输出或工作负载输出。

等待资源就绪 – 在 pod create 或 serverless create 中添加 --wait 会阻塞，直到资源实际可访问（Pod 为 SSH，端点为健康检查）。可通过 --wait-timeout 调整超时时间。

文件传输 – runpodctl send FILE 生成一个短代码；对方运行 runpodctl receive CODE，使用 croc 协议拉取文件。工具会验证路径，防止写入当前目录之外。

输出格式 – 默认命令输出 JSON，但可通过 --output=yaml 请求 YAML 格式。无效格式名称将被明确拒绝。

错误处理 – 错误以包含 code（如 usage_error, wait_timeout）和人类可读 error 字段的 JSON 对象返回。退出码规则：0 表示成功，非零表示失败、超时或作业失败。

谁会受益 – 数据科学家、ML 工程师，或任何需要对 Runpod 的 GPU Pod 和无服务器端点进行程序化控制的人，都可以将这些命令嵌入脚本、CI 流水线或交互式会话中。

---

以上所有细节均直接取自 runpod/runpodctl 仓库的 README。