ucloud-cli

UCloud CLI

公式の ucloud CLI を使用して UCloud リソースを操作します。ユーザーが UCloud アカウントに対する実際のクラウド操作、リソースの確認、またはパラメーター化された自動化タスクを必要としている場合は、製品のサブコマンドを優先して使用してください。製品のサブコマンドが存在しない場合、機能が不足している場合、または意味が明確でない場合に限り、ucloud api による OpenAPI 呼び出しに切り替えてください。

デプロイ関連のリクエストは、このスキルを使用する強いトリガーとして扱ってください。ユーザーが WEB プログラムのデプロイ、サイトの公開、サービスのオンライン化、クラウドホストの準備、パブリックネットワークアクセスの開放、EIP のバインド、ロードバランサーの作成、またはアプリケーション向けのその他の UCloud リソースの設定を希望している場合は、元のクラウド API の呼び出しではなくアプリケーションのデプロイとして表現されたリクエストであっても、このスキルを使用してください。

前提条件

• 実行環境に ucloud CLI がインストールされており、バージョンが v0.3.1 以上である必要があります。
• リソース操作を実行する前に、使用可能な CLI profile が存在する必要があります。使用可能な profile がない場合は、「CLI の初期化と profile の検出」の手順に従い、OAuth 認証による初期化を優先してください。

ucloud CLI がインストールされていない、使用できない、またはバージョンが v0.3.1 より低い場合は、現在のリソース操作を中止してください。オペレーティングシステムとアーキテクチャを確認し、ユーザーの同意を得てから CLI をインストールまたはアップグレードしてください。 Linux では /etc/os-release と uname -m を組み合わせて確認し、macOS では sw_vers と uname -m を使用してください。

インストール方法

1. まずプラットフォーム、CPU アーキテクチャ、現在のバージョンを確認します。x86_64/amd64 には amd64 パッケージを、arm64/aarch64 には arm64 パッケージを使用してください。
2. macOS：Homebrew を使用して管理します。まず brew --version で Homebrew が使用可能か確認してください。Homebrew がインストールされていない場合は、https://brew.sh/ の公式インストールコマンドで Homebrew をインストールすることをユーザーに伝え、実行前にユーザーの許可を得てください。Homebrew が使用可能になったら、ucloud が未インストールの場合は brew install ucloud を実行し、バージョンが古い場合は brew upgrade ucloud を実行してください。
3. Linux：https://github.com/ucloud/ucloud-cli/releases から最新の release を確認し、アーキテクチャに合った ucloud-linux_{amd64,arm64}.zip をダウンロードして解凍します。解凍後の bin/ucloud を実行可能バイナリとして使用し、$PATH 内のディレクトリに配置するか、リンクを作成してください。
4. Windows：https://github.com/ucloud/ucloud-cli/releases から最新の release を確認し、アーキテクチャに合った ucloud-windows_{amd64,arm64}.zip をダウンロードして解凍します。解凍後の bin/ucloud を ucloud.exe としてインストールし、PATH 内のディレクトリに配置するか、リンクを作成してください。
5. インストール先ディレクトリへの権限がない場合は、まずユーザーの許可を求めてください。バイナリを、現在の一時ディレクトリからしか使用できない場所に置かないでください。
6. インストールまたはアップグレードの完了後に ucloud --version または ucloud --help を実行します。コマンドが使用可能で、バージョンが v0.3.1 以上である場合に限り、リソース操作を続行してください。

CLI の初期化と profile の検出

1. まず CLI が使用可能か確認します：ucloud --version または ucloud --help。
2. ユーザーが profile を指定していない場合は、ローカルでアクティブな profile を優先して使用します。ローカル設定を確認する必要がある場合は、ucloud config list または ucloud --config を使用し、出力を機密情報として扱ってください。
3. 確認結果に public key、private key、token、またはその他の認証情報が含まれている場合は、設定の有無を判断するためにのみ内部で使用してください。ユーザーに表示する際は必ずマスキングするか、省略してください。
4. profile がない場合は、OAuth 認証を優先してください。ユーザーの同意を得た後、インタラクティブ環境または非インタラクティブ環境で ucloud auth login を直接実行します。
5. スクリプト、CI/CD、またはユーザーが AK/SK profile を明示的に要求するケースでは、ucloud init または ucloud config add に誘導してください。
6. ユーザーが非インタラクティブ方式での AK/SK profile 作成を明示的に要求した場合は、プレースホルダーを含むコマンドテンプレートのみを提示してください。実際のキーを代入せず、実際のキーを含むコマンドを実行しないでください：

ucloud config add \
  --profile example-profile \
  --public-key YOUR_PUBLIC_KEY \
  --private-key YOUR_PRIVATE_KEY \
  --region cn-bj2 \
  --zone cn-bj2-02 \
  --project-id org-xxxxxx \
  --active true \
  --agree-upload-log false

7. AK/SK の初期化に必要なフィールド：profile 名、public key、private key。任意のデフォルト値には、Region、Zone、ProjectId、BaseUrl、timeout、max retry、および active に設定するかどうかが含まれます。
8. 既存の profile を変更する場合は、ユーザーが現在アクティブにしている設定を上書きしないよう、まず対象の profile 名を確認してください。--profile <name> で正確に呼び出せる場合は、単一の操作のために active profile を切り替えないでください。
9. デフォルト設定の変更をユーザーが明示的に要求した場合に限り、ucloud config update --profile <name> ... --active true を使用してください。CLI が update 時にキーも要求する場合は、引き続きユーザーにはプレースホルダーのテンプレートのみを提示し、コマンドに実際のキーを埋め込まないでください。
10. 初期化または OAuth 認証の完了後、ucloud region、ucloud project list、または同等の読み取り専用コマンドを実行し、profile が使用可能であることを確認してからリソース操作を続行してください。

情報源の優先順位

CLI の呼び出し方法を決める際は、以下の順に情報源を使用してください：

1. ローカルの CLI help 出力と UCloud CLI ドキュメント。製品のサブコマンド、flag、profile の使用方法、インストール済みコマンドの対応範囲を確認するために使用します。
2. UCloud 製品ドキュメント。製品の概念、リソースの関係、制約、ユーザーが使用する用語を確認するために使用します。
3. CLI で該当する製品のサブコマンドがサポートされていない場合、または製品のサブコマンドで現在の操作に対応できない場合は、ucloud api サブコマンドを使用して汎用的に呼び出します。対応する製品のドキュメントを https://github.com/UCloudDoc-Team/api から取得し、Action 名、必須パラメーター、リクエスト構造、レスポンスフィールドを確認してからリクエストを送信してください。
4. 現在のコンテキストで正しい製品コマンド、Action、必須フィールド、またはリソース範囲を判断するための情報が不足している場合は、ユーザーへの質問やリクエストの実行より先に公式ドキュメントを参照してください。
5. ucloud-cli リポジトリ。上記のドキュメントとローカルの help だけではまだ情報が不足している場合に使用します。

製品ルール

製品の別名を特定する場合、デプロイするリソースを決める場合、リソース作成時のデフォルト値を決める場合、または製品固有の制約に対処する場合は、まず references/product-rules.md を読み、索引に従って該当する製品ファイルを読み込んでください。本文には、汎用的な CLI、profile、安全性、出力のルールのみを残します。

呼び出しフロー

1. ユーザーのリクエストは、ucloud uhost ...、ucloud eip ...、ucloud ulb ... などの製品専用コマンドへの変換を優先します。
2. まずローカルの ucloud --help、ucloud <product> --help、ucloud <product> <subcommand> --help、および CLI ドキュメントを確認し、製品のサブコマンドが現在のタスクに対応しているか、必要な flag は何か、ProjectId、Region、Zone が必要かどうかを確認してください。
3. 製品のサブコマンドが存在しない、必要な機能が不足している、または動作が不明確な場合に限り、リクエストを DescribeULB などの OpenAPI Action に変換してください。ucloud api でリクエストを実行する場合は、先に https://github.com/UCloudDoc-Team/api で対応するインターフェースを確認してください。
4. 使用する CLI profile を確認します：
   • ユーザーが profile を指定した場合は、その profile を明示的に使用します。
   • それ以外の場合は、ローカルでアクティブな profile を使用します。
5. 対象リソースの識別子と、選択した製品コマンドまたは API Action に関連する必須フィールドが揃っているか確認してください。
6. CLI に使用可能なアクティブ profile がなく、ユーザーも profile を指定していない場合は処理を中止し、先に profile を初期化または設定するようユーザーに依頼してください。
7. 必ず補足が必要な情報がある場合は、不足しているフィールドのみを簡潔に列挙してユーザーに質問してください。
8. ユーザーの回答に含まれる値を構造化データとして解析し、製品コマンドの flag または API JSON payload に統合してください。
9. 選択したコマンドまたは API で必要であり、かつユーザーまたは環境から提供されている場合に限り、ProjectId、Region、Zone を追加してください。
10. 製品のサブコマンドを使用できる場合は、対応する ucloud <product> <subcommand> を実行します。API に切り替える必要がある場合は、JSON payload を一時ファイルに書き込み、ucloud api --local-file <file> を実行してください。
11. 後続の変更操作を実行する前に、クエリ結果またはレスポンス内容を確認してください。

呼び出し方法の選択

デフォルトでは、製品専用の CLI サブコマンドを使用します。ユーザーの意図により近く、パラメーターの意味が明確で、公式 CLI の高レベルな操作入口にも合致するためです。ユーザーが profile を指定していない場合は、--profile を省略して、CLI にローカルで有効化された設定を使用させます。 製品サブコマンドが存在しない場合、必要な機能が不足している場合、ネストされた payload を表現できない場合、またはローカルの help から製品の意味に沿った正しい呼び出し方法を確認できない場合に限り、ucloud api --local-file の Raw Action モードにフォールバックします。

# 1. 将 payload 写入临时文件
cat > /tmp/ucloud-request.json << 'EOF'
{
  "Action": "DescribeULB",
  "ULBId": "ulb-xxxx"
}
EOF

# 2. 调用
ucloud --profile prod-account api --local-file /tmp/ucloud-request.json

# 3. 清理
rm -f /tmp/ucloud-request.json

小さな payload では、inline flag 形式も使用できます。

ucloud --profile prod-account api --Action DescribeULB --ULBId ulb-xxxx

API にフォールバックする前に、製品サブコマンドが利用できない、または適さない理由を記録します。小さな payload では inline flag 形式も使用できます。大きい payload やネストされた payload では、--local-file を使用します。

作業ルール

• 既存のリソースに影響する可能性があるリクエストでは、読み取り専用のクエリーコマンドまたは読み取り専用の Action を優先します。
• 書き込み操作または削除操作を実行する前に、説明文に具体的な製品コマンドを明記します。API にフォールバックする場合は、具体的な Action 名を明記します。
• 書き込み操作または削除操作を実行する前に、使用する profile または設定元を明記します。
  • ユーザーが指定した場合は Profile: <name> と出力します。
  • ローカルで有効化された設定を使用する場合は Profile: active と出力します。
• CLI のデバッグログはデフォルトで無効です。ユーザーがログの出力を明示的に求めた場合、または詳細なデバッグ出力をリクエストした場合に限り、有効にします。
• ユーザー向けの結果は、明確で整形された構造で提示します。生の JSON ダンプではなく、簡潔なセクション、Markdown テーブル、ラベル付きのフィールドを優先します。
• 説明文、計画、コマンドのプレビュー、パッチテキスト、ユーザー向けの要約に UCLOUD_PUBLIC_KEY、UCLOUD_PRIVATE_KEY、または生の鍵情報を表示、繰り返し、埋め込むことは絶対にしません。
• コマンドラインで認証情報を収集するより、既存の CLI profile を優先します。コマンドライン、会話、ツールログ、コマンドのプレビューは、閲覧可能で安全ではないチャネルとして扱います。
• API にフォールバックし、payload が大きい場合は、長いインライン JSON ではなく --local-file を使用します。
• パラメーター名を捏造しません。必須パラメーターが不明な場合は、実行前に公式ドキュメントを確認します。
• ucloud api 呼び出しにフォールバックするたびに、記憶や製品コマンドの help のみに頼ってパラメーターを推測するのではなく、https://github.com/UCloudDoc-Team/api で正確なインターフェース定義を確認します。
• 製品サブコマンドの形式、必須フィールド、またはリソースの意味が不明な場合は、まず CLI help、CLI ドキュメント、製品ドキュメントを確認します。それでも確認できない場合は、公式 API ドキュメントを参照し、推測しないでください。
• ユーザーが書き込み操作をリクエストし、識別子が曖昧な場合は、まずクエリーを実行し、返されたデータに基づいて正確な対象を確認します。
• 情報が不足している場合は、実行を妨げるフィールド（Region、ProjectId、ULBId、想定する profile 名など）のみを尋ねます。
• ユーザーの回答後、値を正確な製品コマンドの flag または API フィールド名に正規化し、プロセス全体をやり直すことなく実行を続けます。
• ユーザーが自由形式のテキストと構造化データを混在させて提供した場合は、使用可能な値を抽出し、解析したコマンドパラメーターまたは payload を簡潔に提示してから実行します。
• 最終的に ucloud api --local-file が必要な場合でも、その操作に適した製品サブコマンドがないことを先に確認します。

出力スタイル

• デフォルトでは簡潔な Markdown を使用し、Action、Result、Resources、Errors、Next Steps などの明確なセクションラベルを付けます。
• 単一のリソースまたは単一の操作結果では、フィールド | 値 のような2列のテーブルを優先します。
• 複数のリソースでは、簡潔なテーブルを優先し、リソース ID、名前、ステータス、Region、Zone、IP、課金方式など、判断に最も重要な列を優先して表示します。
• テーブルが適さない場合に限り、後続の操作や注意事項を列挙するなど、リストを使用します。
• ユーザーが生のレスポンスを明示的に求めた場合を除き、生の JSON をそのままダンプしないでください。まず要約し、タスクに関連する重要なフィールドのみを表示します。
• 実行前に解析済みのリクエストパラメーターを提示する場合は、ユーザーが対象範囲をすばやく確認できるよう、簡潔なラベル付きリストまたはテーブルで示します。
• すべての整形済み出力で、鍵と機密トークンをマスクするか省略します。
• 結果が大量にある場合は、長すぎるレスポンスを貼り付けるのではなく、関連性の高い数行の要約テーブルを先に表示し、ほかにも項目があることを伝えます。

不足情報の処理

• 範囲の不足： 選択した製品コマンドまたは API Action で必要とされ、環境にも存在しない場合に限り、ProjectId、Region、Zone をユーザーに尋ねます。
• 任意のデフォルト範囲： CLI profile、ユーザーコンテキスト、環境変数 UCLOUD_PROJECT_ID、UCLOUD_REGION、UCLOUD_ZONE、UCLOUD_BASE_URL からデフォルト範囲を読み取ることができます。これらは前提条件ではなく、コマンドで必要とされ、ユーザーが明示的に指定していない場合にのみ使用します。
• 対象リソースの不足： ULBId、EIPId、VPCId、InstanceId など、コマンドまたは API 固有の正確な ID をユーザーに求めます。
• コマンドまたは Action のパラメーターの不足： CLI help、CLI ドキュメント、製品ドキュメント、必要に応じた API ドキュメント、現在のコンテキストを確認しても不足している必須フィールドのみをユーザーに尋ねます。
• 回答を受け取った後： 回答をコマンドパラメーターまたは JSON オブジェクトに変換し、既存のパラメーターと統合して、ユーザーにリクエスト全体を再度説明してもらうのではなく、同じ製品コマンドまたは API Action の実行を続けます。

エラー処理

• エラーが発生した場合、現在のコンテキスト、CLI help、公式ドキュメント、lookup API から安全な修正方法を導き出せるなら、まず自動的に診断して修正を試みます。
• むやみに再試行しないでください。再試行するたびに、明確な診断に基づいて行います。
• 299 IAM permission error を直ちに権限不足と見なさず、まず API 定義に基づいて ProjectId の不足がないか確認します。
• 具体的な再試行条件、299 の振り分けルール、profile の失敗処理、エラー報告の形式については、references/error-handling.md を参照してください。

汎用 Lookup API

共通パラメーターが不足している場合、ユーザーに尋ねる前に lookup API を使用して調べます。

• ListRegions：Region が不足している場合、またはユーザーが都市名や製品名のみを指定した場合に、利用可能な Region を確認します。
• ListZones：Zone が不足しており、選択した Region が判明している、または推測できる場合に、利用可能な Zone を確認します。
• GetProjectList：ProjectId が不足している場合に、アクセス可能なプロジェクトを確認します。
• GetBalance：課金対象リソースを作成する前に、クォータや請求の準備状況が操作に影響する可能性がある場合に、アカウント残高を確認します。

これらの lookup API を使用して、不足している値の候補を絞り込みます。クエリー後も有効な候補が複数ある場合は、簡潔なリストにしてユーザーに提示し、選択を求めます。具体的な呼び出し方法、フィールドの抽出ルール、例については、references/common-lookups.md を参照してください。

使用例

製品サブコマンドを優先

ucloud uhost list --region cn-bj2
ucloud eip list --region cn-bj2

API inline flag 形式（製品サブコマンドが利用できず、payload が小さい場合）

ucloud api --Action DescribeInstance --region cn-bj2

API local file 形式（製品サブコマンドが利用できず、payload が大きい、またはネストされている場合）

cat > /tmp/ucloud-request.json << 'EOF'
{
  "Action": "DescribeULB",
  "Region": "cn-bj2",
  "ULBId": "ulb-xxxx"
}
EOF
ucloud --profile prod-account api --local-file /tmp/ucloud-request.json
rm -f /tmp/ucloud-request.json

ローカルで有効化された profile を使用

ucloud uhost describe --region cn-bj2

1回の呼び出しで CLI debug を有効化

UCLOUD_CLI_DEBUG=on ucloud uhost list --list cn-bj2

英数字のパスワードを生成

tr -dc 'A-Za-z0-9' </dev/urandom | head -c 20

参考資料

• 製品サブコマンドと ucloud api のフォールバック経路で、どの公式情報源を信頼すべきか判断する必要がある場合は、まず references/doc-sources.md を読みます。このファイルでは参照順序を定義し、https://github.com/UCloudDoc-Team/api を案内しています。
• ユーザーのリクエストを実際の CLI 呼び出しに変換する必要がある場合は、製品サブコマンドの優先順位、profile の選択ルール、ucloud api --local-file、payload の構造に関する規約を含む references/cli-usage.md を読みます。
• 製品の別名、デプロイリソースのデフォルト値、製品固有の制約を特定する必要がある場合は、references/product-rules.md を読み、索引から該当する製品ファイルを参照します。