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；未推斷任何額外功能。