runpod/runpodctl

runpodctl の機能

runpodctl は RunPod 用のコマンドラインクライアントであり、GPUを搭載したコンテナ（pods と呼ばれる）およびサーバーレス推論エンドポイントを起動・管理できます。このツールを使えば、ターミナルからリソースの作成・起動・停止・削除・照会、サーバーレス関数の実行、ファイルの転送がすべて可能になります。

使用対象者

訓練や実験にオンデマンドのGPUマシンが必要な AI研究者 / 開発者
サーバーレスエンドポイントとして推論モデルをデプロイし、迅速にテストや監視を行いたい MLエンジニア
HTTP呼び出しを書かずに計算リソースをプログラムでプロビジョニングしたい 自動化スクリプト や AIエージェント

主要機能

分野	コマンド（名詞-動詞形式）	機能
Pod管理	`runpodctl pod list/get/create/update/start/stop/delete`	既存のGPUポッドの一覧表示、ポッドの詳細確認、Dockerイメージから新しいポッドの起動、設定の変更、ライフサイクルの制御
サーバーレスエンドポイント	`runpodctl serverless list/get/create/update/delete/run/status/health`	「サーバーレス」推論サービスの管理、JSONペイロードで実行、ジョブステータスのポーリング、ワーカーの健全性確認
準備完了待ち	`--wait`（`pod create` または `serverless create` で使用）	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️⃣ 現在のポッド一覧を表示
runpodctl pod list

# 3️⃣ 新しいGPUポッドを起動（例：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優先出力：成功したすべてのコマンドは stdout に1つのJSONオブジェクトを出力。他のプログラムやLLM駆動エージェントからの利用が容易。
stdout / stderr の分離：データ（ポッド情報、ジョブペイロード）は stdout へ、進捗メッセージやエラーは stderr へ。ストリームの混在を回避。
安定したエラーコード：すべてのエラーに小文字の code（例：not_found, rate_limited）を含む。スクリプトはHTTPステータスや自由形式テキストではなく、このフィールドに基づいて分岐すべき。
待機のセマンティクス：--wait はリソースが利用可能（ポッドはSSH接続可能、サーバーレスは少なくとも1つのワーカーが準備完了）になるまでブロック。タイムアウトは設定可能（--wait-timeout）。待機中に中断してもリソースは削除されず、CLIはリソースIDを返すため後でクリーンアップ可能。
非隠し同期エンドポイントなし：CLIは常に非同期の /run API を使用し、/status をポーリング。/runsync エンドポイントの欠点（課金が残る、結果の保持期間が短い）を回避。

使わない方が良い場合

RunPodをWeb UIまたは高レベルSDKでしか使わない場合、runpodctl のインストールはほとんど価値がありません。CIパイプライン、リモートシェル、または自律型AIエージェントの一部として、軽量でスクリプト可能なインターフェースが必要な場合にこそ、このツールの真価が発揮されます。

上記のすべての詳細はプロジェクトのREADMEから直接引用；追加機能は推測されていません。