volcengine-cli

Volcengine CLI スキル

Volcengine OpenAPI、TOS オブジェクト操作、Ark 製品のワークフロー、TLS ログサービスのワークフローには、統一されたエントリーポイントとして ve を使用します。

エージェント呼び出し元のメタデータ（必須）

エージェントが起動するすべての ve プロセスには、ヘルプ／バージョン確認、認証、API 呼び出し、再試行、ポーリング、ve tosutil／ve arkcli／ve volclog を含め、次の環境変数を設定する必要があります。

変数	必須値
VE_CALLER_TYPE	常に ai_agent です。
VE_CALLER_NAME	現在のランタイム環境から、実際のエージェントホスト識別子を解決します。これはエージェントアプリケーションを識別するものであり、モデル、アカウント、ユーザー、セッションを識別するものではありません。
VE_SKILL_NAME	実行中のワークフローで有効な Volcengine スキルのフロントマターにある name を解決します。実際の volcengine-* 名を使用します。

これらの値はユーザー自身で設定してください。これはランタイムの帰属情報であり、認証情報でもユーザーのセットアップ手順でもありません。 固定値なのは VE_CALLER_TYPE=ai_agent だけです。実行のたびに現在のホストと有効なスキルを解決してください。どちらにもハードコードされたデフォルト値はありません。たとえば、現在のエージェントが Codex の場合に限り codex が有効であり、現在の操作をそのスキルが担当する場合に限り volcengine-cli が有効です。エージェント環境または有効なスキルが変わったら、値を再度解決してください。共有ヘルパーや上流の製品 CLI には、呼び出し元である Volcengine スキルの実際の ID が引き継がれます。実行ファイル名やインストール先のディレクトリによって ID が決まることはありません。

ツールのプロセス環境またはコマンド単位の代入を使って、実行のたびに3つすべてを渡してください。新しいツール呼び出しでは新しいシェルが起動することがあるため、以前の export だけでは不十分です。複数コマンドを含むシェルブロックでは、そのブロックの先頭で3つすべてをエクスポートし、ワークフローを切り替える前にスキル名を更新してください。代入は実行ファイルの前に置いてください。CLI フラグ、API パラメーター、リクエストボディに追加するフィールドではありません。 パイプラインや $(...) では、ve プロセス自体に変数を設定するか、パイプラインの実行またはコマンド置換の展開前に、同じシェルで変数をエクスポートしてください。

コマンド形式 — エージェントは実行前に、実際のランタイム環境と有効なスキルから解決した値で両方のプレースホルダーを置き換える必要があります。

VE_CALLER_TYPE=ai_agent \
VE_CALLER_NAME="<agent-id>" \
VE_SKILL_NAME="<current-volcengine-skill>" \
  ve ecs DescribeInstances --output json

install_ve.sh、ve_login_remote.sh、audit_extend_apis.py、call_extend_api.py など、ve を起動するスクリプトにも同じ環境を適用してください。子プロセスは環境を継承します。デタッチされたログインプロセスも含まれます。後でヘルパーを呼び出す際には、再度環境を渡す必要があります。ダウンロードしたインストーラーをパイプ経由で実行する場合は、ダウンロードコマンドだけではなく、インストーラーを実行するシェルに環境を設定してください。必要な認証／設定と子 CLI の引数は保持し、呼び出し元メタデータについては、以下の Ark 委譲ルールに従ってください。

このスキルとその参照先のコマンド例ではコマンド構文を示しています。ここで説明する環境要件は、これらの例を実行する場合にも適用されます。

Ark 委譲：呼び出し元変数は一組のみ

ve arkcli ... では、上記の VE_* 呼び出し元変数を3つ設定してください。ve がそれらを Ark CLI の環境変数に変換するため、エージェントは ARKCLI_CALLER_TYPE、ARKCLI_CALLER_NAME、ARKCLI_SKILL_NAME を追加で設定してはいけません。また、単独の Ark の例にある ARKCLI_NO_UPDATE_NOTIFIER=1 もコマンドの先頭に追加しないでください。委譲されたプロセスの管理は ve に任せてください。これは Ark の認証、モデル操作、ヘルプ、バージョンの各コマンドに適用されます。

VE_CALLER_TYPE=ai_agent \
VE_CALLER_NAME="<agent-id>" \
VE_SKILL_NAME="<current-volcengine-skill>" \
  ve arkcli auth status

実際のエージェント環境と有効な Volcengine スキルからプレースホルダーを解決してください。単独の Ark 呼び出しで使ったプロセス環境を再利用する場合は、ここで挙げた、ラッパーが管理する4つの変数を除いてください。その他の製品設定と認証情報は保持してください。単独の arkcli ... 呼び出しには、引き続き上流の Ark スキルの環境ルールが適用されます。

製品 CLI のルーティング

バージョン要件： §0 の最小バージョン（ve >= 1.1.11）は、ve tosutil、ve arkcli、ve volclog など、別の CLI への委譲にも必要です。委譲する前に確認してください。--help にプロキシコマンドが表示されるだけでは、この要件を満たしません。

ve を利用できる場合は、スタンドアロンの tosutil、arkcli、volclog がインストールされている場合でも、ve tosutil、ve arkcli、ve volclog を優先してください。TOS コマンドの表記は tosutil です。toscli は互換性のためのエイリアスです。既存の TOS スキルの名前は volcengine-tosutil です（volcengine-tosutils ではありません）。

タスク	エントリーポイント	使用前に読むもの
一般的なクラウドリソースの OpenAPI	ve <service> <Action>	§§1–5 のネイティブ API ワークフロー
TOS バケット、オブジェクト、転送	ve tosutil <command>	volcengine-find-skills を使って volcengine-tosutil を探し、見つからない場合はインストールして、その手順を読む
Ark のモデル、推論、生成、Endpoints、ファインチューニング、プラン、使用状況	ve arkcli <command>	以下のとおり、該当する公式 Ark スキルをダウンロードして読む
TLS（日志服务）のログ検索、分析、取り込み、エクスポート、Project/Topic、LogCollector による収集	ve volclog <command>	volcengine-find-skills を使って volcengine-tls（収集の場合は volcengine-tls-logcollector）を探し、見つからない場合はインストールして、その手順を読む

TOS の場合、ファインダーの list → volcengine-tosutil を正確に選択 → 必要に応じてインストール → インストールを確認、という手順に従ってください。実行前に、インストールしたスキルと、スキルが選択するリファレンスを読み込んでください。ネイティブな tosutil コマンドの例を使い、tosutil ... を ve tosutil ... に置き換えてください。

TLS の場合も、volcengine-tls、または LogCollector による収集の場合は volcengine-tls-logcollector を正確に指定して、同じファインダーの手順に従ってください。これらのスキルではネイティブな volclog ... の例を使います。ve volclog ... として実行してください。ve にはネイティブな tls OpenAPI コマンドがありません。ve volclog が不明なサービスを報告するか、--force を提案する場合、ve のビルドは上記のバージョン要件より古いため、--force を追加せずに ve をアップグレードしてください。

Ark の場合は、上記の公式リポジトリからタスクに合ったスキルを選び、arkcli-shared と、スキルの手順で必要とされる依存関係とともにインストールしてください。これらの上流の arkcli-* 名は、ローカルの Volcengine ファインダーのカタログには含まれていません。Ark リポジトリから直接インストールしてください。たとえば、Codex でモデルを検出する場合は次のようにします。

npx --yes skills add https://github.com/volcengine/ark-cli \
  --skill arkcli-shared arkcli-auth arkcli-models --agent codex --yes --copy --full-depth
npx --yes skills list --agent codex --json

実際に使用するホストの --agent とタスクスキル名を指定してください。既定ではプロジェクトスコープでインストールされます。ユーザーレベルでインストールする場合に限り、両方のコマンドに --global を追加してください。実行前に名前を確認し、インストールした arkcli-shared/SKILL.md、タスクスキル、およびスキルが選択したリファレンスを読んでください。ホストが新たにインストールしたスキルを読み込めない場合は、ファインダーの指示に従い、元のタスクと完了したコンテキストを引き継いで新しい会話を開始してください。製品の手順は各スキルに任せてください。このスキルの役割は、それらへの案内のみです。

arkcli、tosutil、volclog は透過的に委譲される CLI です。例では実行ファイルのプレフィックスだけを置き換え、それ以降の引数はすべてそのままにしてください。それぞれ独自の認証、プロファイル、パラメーター、出力、終了コードを保持します。--output、--query、--force、--detail、PascalCase パラメーター、--DryRun などのネイティブ API のルールは適用されません。

• 対応している子フラグは、子コマンドの後に指定してください。ve --profile <name> arkcli ... は無効です。 ve arkcli ... --profile <name> は ve のプロファイルではなく、Ark のプロファイルを選択します。
• 製品のスキルに従って、認証、フラグ、出力の処理を行ってください。子コマンドの引数はすべてそのままにして、tosutil ... / arkcli ... / volclog ... を ve tosutil ... / ve arkcli ... / ve volclog ... に置き換えてください。 ve arkcli では、Ark の委任 の説明にある VE_* 呼び出し元メタデータのみを使用してください。単体の Ark 用呼び出し元／通知プレフィックスはコピーしないでください。必要な製品環境変数の設定は ve の前に置いてください。
• ve sts GetCallerIdentity が動作しても、いずれかの子コマンドが認証済みであることの証明にはなりません。選択した製品のスキルに従ってください。ヘルプ、バージョン、ローカルプレビューのタスクでは、ネイティブ API ログインは不要です。
• ve は委任の前に、現在の Console Login セッションを更新することがあります。ただし、その更新によってすべての ve 認証情報やプロファイル設定が子コマンドの設定に反映されるわけではありません。更新に関する警告だけでは、子コマンドが失敗したとは判断できません。

製品 CLI のインストールとアップグレード

ve はまず PATH から子コマンドを探し、次に管理対象ディレクトリを確認します。子コマンドが見つからない場合は、初回使用時に公式 CDN からチェックサムを検証してインストールします。製品を別途インストールする必要はありません。タスクに必要な子コマンドだけを確認してください：

ve tosutil version
ve tosutil help
ve arkcli --version
ve arkcli --help
ve volclog --version
ve volclog --help

管理対象の子コマンドは、ve proxycli upgrade tosutil、ve proxycli upgrade arkcli、または ve proxycli upgrade tls-cli でアップグレードできます。管理コマンドでは製品 ID（TLS の場合は tls-cli）を指定し、実行時にはネイティブのコマンド名（ve volclog）を使用します。 これらのコマンドは、PATH 上の外部インストールには手を加えず、元のパッケージマネージャーに委ねます。ve だけをアップグレードしても、外部インストールはアップグレードされません。子コマンドが ve --help に表示されない場合は、まず ve をアップグレードしてください。製品フラグと利用可能な機能は、解決された子コマンドのヘルプに従います。

---

0. ve CLI のインストールまたはアップグレード

常に最新リリースを実行してください。このスキルでは、現行の ve（デバイスコード方式の ve login、--output／--query、--force、--detail、二重ダッシュ形式のシステムフラグ）を前提としています。古いビルドへのサポート経路はありません。代わりにアップグレードしてください。

最低バージョン（必須）： タスクで最初の他の ve コマンド（ネイティブ OpenAPI 呼び出し、ログイン、製品 CLI への委任を含む）を実行する前に、ve version を実行し、ve >= 1.1.11（安定版リリースの 1.1.11 以降）であることを確認してください。ve が見つからない、1.1.11 より古い、またはバージョンを確認できない場合は、以下のいずれかの方法でインストールまたはアップグレードし、続行する前にもう一度 ve version を実行してください。npm が引き続き古いバージョンをインストールする場合は、設定されている npm ミラーの更新が遅れている可能性があります。その場合は CDN インストーラーまたは GitHub Releases を使用してください。

オプション 1：npm（推奨）

npm i -g @volcengine/cli

オプション 2：CDN インストーラー（Node.js がない場合、または npm に接続できない場合）

curl -fsSL https://cloudcache.volccdn.com/ve/install.sh | sh
# or
wget -qO- https://cloudcache.volccdn.com/ve/install.sh | sh

同じスクリプトが scripts/install_ve.sh として同梱されています。CDN から最新バージョンを取得し、ホストの OS／CPU に対応するアーカイブをダウンロードして、公開されている SHA256SUMS と照合して検証します。書き込み可能な場合は /usr/local/bin にインストールし、それ以外の場合は ~/.local/bin にインストールします（sudo は使用しません）。macOS の隔離フラグを解除し、ve skills update を実行します。--version <ver>、--install-dir <dir>、--dry-run、および VE_VERSION／VE_INSTALL_DIR／VOLCENGINE_CLI_DOWNLOAD_BASE_URL／VOLCENGINE_CLI_SKIP_SKILLS 変数については、スクリプトのヘッダーに記載されています。Windows の場合は、npm またはリリースページを使用してください。

オプション 3：GitHub Releases — https://github.com/volcengine/volcengine-cli/releases

ネイティブ OpenAPI 機能の確認： ve login --help に --no-browser が表示され、ve ecs DescribeInstances --help の System Flags に --output が表示される必要があります。どちらかが表示されない場合は、npm i -g @volcengine/cli@latest でアップグレードするか、CDN インストーラーを再実行してから続行してください。これらの確認は、上記の最低バージョン要件の代わりにはなりません。

---

1. ネイティブ OpenAPI の初期化（API 呼び出し用）

このセクションは、ve <service> <Action> と拡張ヘルパーに適用されます。委任された製品コマンドについては、まず 製品 CLI のルーティングに従い、選択した製品スキルを使用してください。

CLI システムフラグ

すべての ve <service> <Action> 呼び出しでは、Action の後に次のフラグを指定できます。いずれもハイフンは 2 つです。

フラグ	目的
--profile <name>	この呼び出しに限り、設定済みのプロファイルを使用します
--region <region>	この呼び出しに限り、リージョンを上書きします
--endpoint <host>	この呼び出しに限り、エンドポイントを上書きします
--lang EN|ZH	この呼び出しの表示言語
--version <YYYY-MM-DD>	API バージョン。省略時はメタデータのデフォルトを使用します（--force と併用する場合は必須）
--method GET|POST	HTTP メソッド。メタデータのデフォルトがあればそれを使用し、なければ GET を使用します
--force	メタデータの検証（§3）をスキップします。値は不要です。--force true のようには指定しないでください
--output <fmt> / --query <jmespath>	応答のフォーマットと射影（§4）
--header Name=Value、--body '{...}'	カスタムヘッダー／生の JSON ボディ

API パラメーターはパスカルケース（--Region、--InstanceIds.1）、システムフラグは小文字（--region）なので、通常は名前が衝突しません。API パラメーターの名前が小文字のシステムフラグと完全に一致する場合（独自の --query または --lang フィールドを持つ API の場合）に限り、システムフラグを 3 つのハイフンで記述し（---query）、API パラメーターは 2 つのハイフンのままにしてください。それ以外の場所では、ハイフン 3 つのフラグを使用しないでください。

CLI 管理コマンド（ve configure ...、ve login、ve sso login）とヘルパースクリプトでは、--help に表示されるとおり、それぞれ独自のハイフン 2 つのフラグを使用します。

プロファイルの選択（会話中は固定）

ve はプロファイルを通じて異なる認証情報を使用できますが、エージェントが独自にプロファイルを選択してはいけません。

• ユーザーがプロファイルを明示的に選択していない場合は、CLI のデフォルト解決を使用します。ve sts GetCallerIdentity を直接実行してください。最初にすべてのプロファイルを一覧表示して、自分で選択してはいけません。
• ユーザーがプロファイルを明示的に選択した場合は、この会話での後続のすべてのコマンドでも同じプロファイルを使い続けます：ve ecs DescribeInstances --profile prod、python3 scripts/call_extend_api.py --profile prod ...。
• プロファイル名、リージョン、一覧の順序、最近の利用状況、成功率、タスクの内容から、希望するプロファイルを推測してはいけません。
• デフォルトの ID がタスクのリスクに適合しない場合、またはプロファイルの選択が必要な場合は、現在のデフォルト ID をユーザーに伝え、候補のプロファイル名のみを一覧表示して、ユーザーの選択を待ってください。
• この会話でプロファイルが固定された後は、ユーザーから明示的に切り替えを求められない限り、別のプロファイルに切り替えてはいけません。

認証情報が使用可能であることを確認するため、ID 確認コマンドを実行してください：

ve sts GetCallerIdentity

成功 — 現在のアカウント ID とリージョンをユーザーに伝えてから、タスクを進めてください。

後からリージョンを切り替える場合：サービス API 呼び出しで --region を指定すると、その呼び出しに限ってリージョンが上書きされます（応答の Region もそれに応じて変わります）。また、プロファイルにデフォルトのリージョンが設定されていない場合は、VOLCENGINE_REGION がデフォルトになります。変わらないのは、プロファイルに紐付けられたログインセッション／アカウントです。リージョンの上書きはリクエストの送信先を変えるだけで、ユーザーの ID は変わりません。独自にリージョンやプロファイルを切り替えてはいけません。ユーザーから明示的に求められた場合に限り、--region を指定するか、プロファイルを切り替えてください（ve configure profile --profile <name>）。ve configure list は候補のプロファイル名を表示する場合にのみ使用してください。一覧表示後、自分でプロファイルを選んではいけません。これは ve login 自体に指定する --region フラグとは別です。こちらは必須です（下記を参照）。

失敗 — 使用可能なプロファイルがありません。デフォルトの手順は ve login（コンソールログイン）です。最初にこの手順をユーザーに伝え、「AK/SK を使う」「STS トークンを使う」「SSO を使う」と伝えれば切り替えられることも案内してください。

以前は使用できていたセッションがタスクの途中で期限切れになった場合も、同じ手順を適用します。どのスキルがコマンドを発行したかにかかわらず、ve コマンドで failed to refresh session token. Please run 've login' to re-authenticate（または類似のトークン更新／セッション期限切れメッセージ）が発生した場合は、これと同じ失敗です。エラー文はユーザーに ve login の実行を求めていますが、その指示をユーザーに伝えたり、ユーザー自身のターミナルで実行するよう求めたりしてはいけません。以下のコンソールログイン手順を自分で実行し、サインインリンクのみをユーザーに渡してください。再ログインの対象は、使用中だったプロファイルでなければなりません。会話の前半でプロファイルが固定されている場合は、start にそのプロファイルを渡し、ログインとその検証の両方が同じプロファイルを対象とするようにしてください。プロファイルを省略すると default が更新され、固定されたプロファイルは使用できないままになり、デフォルトのアカウントコンテキストが汚染されます。

デフォルト：scripts/ve_login_remote.sh を使用したコンソールログイン

ve login を直接実行しないでください。必ず scripts/ve_login_remote.sh を使用してください。 ve login はデバイスコードフローです。ve が確認用 URL とユーザーコードを表示し、ユーザーが任意のデバイスのブラウザーで承認するまでポーリングします。デバイスコードはその ve プロセス内にしか保持されないため、このヘルパーはプロセスを切り離し（setsid）、ツール呼び出しの境界を越えても実行が続くようにして、URL とコードを記録し、ve のプロンプトに応答して、結果を検証します。自分で ve login を呼び出すとプロセスが孤立し、連携が失われます。

会話で最初に start を実行する前に、references/console-login.md を最後まで読んでください。そこには、手順、すべての終了コード、start-wait のバリエーション、調整方法、フローが中断される要因の全リストが記載されています。形式は次のとおりです。

scripts/ve_login_remote.sh start <region> [profile]   # prints URL= CODE= LINK= EXPIRES_IN= NEXT=
scripts/ve_login_remote.sh url                        # same block, never blocks (11 = not yet, 3 = process gone)
# hand the user LINK (fallback: URL + CODE), end the turn, wait for "done"
scripts/ve_login_remote.sh verify [profile]           # 0 ok · 11 still pending · 13 logged in but API unreachable · 10 start over
scripts/ve_login_remote.sh abort                      # on user interrupt / expired code, then start again

リージョン：ユーザーが指定したもの、指定がなければ VOLCENGINE_REGION、それもなければ cn-beijing です。ユーザーが以前にプロファイルを固定した場合に限り [profile] を渡し、start と verify の両方に同じ値を渡してください。

リファレンスを読んでいない場合でも、次の不変条件を必ず守ってください。

• 計画と、切り替え方法（「use AK/SK」と言えば切り替えられます）を伝えてから start を実行してください。ログイン方法のメニューを提示してはいけません。
• start が応答しなくなったり、強制終了されたりしても、何も証明されません。何かを結論づける前に url／status を呼び出してください。これを理由に start や abort を再試行したり、nohup に切り替えたりしてはいけません。
• ユーザーが貼り返すものはありません。認証コードはありません。ユーザーから承認したと伝えられたら verify を実行してください。
• verify の終了コード 13 は、ログインが成功したものの、ホストが open.volcengineapi.com に接続できないことを意味します。ログインをやり直してはいけません。
• 表示されたとおりの LINK を使用してください。signin.volcengine.com の URL を作成したり、以前のプロセスで使った URL を再利用したりしてはいけません。
• start の終了コード 4 は、ve がインストールされていないか、デバイスコードログインに対応していないほど古いことを意味します。§0 に従ってインストール／アップグレードしてから、再試行してください。

ve login が失敗した場合（ネットワークエラー、start の終了コード 4、どのデバイスにもブラウザーがない場合）、またはユーザーが別の方法を求めた場合は、以下の代替手段に切り替えてください。

代替手段：AK/SK（長期認証情報。CI/CD またはスクリプト向け）

AccessKey と SecretKey をユーザーに尋ねてから、次の手順を実行してください。

ve configure set --profile default --region cn-beijing \
  --endpoint open.volcengineapi.com \
  --access-key <AK> --secret-key <SK>

STS（一時）認証情報の場合は、--session-token <TOKEN> も渡してください。

現在のシェルでのみ有効な代替方法：VOLCENGINE_ACCESS_KEY、VOLCENGINE_SECRET_KEY、VOLCENGINE_REGION をエクスポートし、必要に応じて VOLCENGINE_SESSION_TOKEN もエクスポートします。

代替手段：SSO／Cloud Identity Center（エンタープライズフェデレーション向け）

3 ステップで設定します。最初に SSO の開始 URL とセッション名をユーザーに尋ねてください。

ve configure sso-session --name <session-name> \
  --start-url https://<sso-host>/userportal \
  --region cn-beijing \
  --registration-scopes cloudidentity:account:access,offline_access

ve configure sso --profile <profile-name> --sso-session <session-name>

ve configure profile --profile <profile-name>

次に ve sso login --sso-session <session-name> を実行します（ヘッドレスマシンでは --no-browser を使用してください）。

認証情報の安全性

• ~/.volcengine/config.json は絶対に読み込まないでください。AK/SK とセッショントークンが含まれています。
• --secret-key を指定して ve configure set を実行する場合は、Claude 経由で実行するのではなく、ユーザー自身のシェルでコマンドを貼り付けて実行してもらうことを優先してください。コマンドライン引数として渡されたシークレットは、シェルの履歴やプロセス一覧に残ります。
• AK/SK、シークレットキー、セッショントークンをプレーンテキストでユーザーに表示してはいけません。

---

2. 安全ルール（必須）

読み取り／書き込みの分類

レベル	操作の種類	動作
読み取り専用	Describe* / List* / Get* / Query*	そのまま実行します。確認は不要です
書き込み	Create* / Run* / Allocate* / Attach* / Associate* / Authorize*	コマンド全体を表示し、ユーザーの確認を待ちます
破壊的操作	Delete* / Terminate* / Release* / Revoke* / Modify* / Stop* / Detach*	コマンドと影響の概要を表示し、ユーザーの確認を必須とします

基本原則

1. デフォルトは読み取り専用 — ユーザーが変更を明示的に要求しない限り、読み取り専用モードで実行します
2. まず DryRun — 書き込み／破壊的操作が --DryRun true に対応している場合は、DryRun を実行して計画を確認し、実行前に確認を取ります
3. 実行前に確認 — 書き込み操作のコマンド全体を提示し、承認を待ちます
4. 認証情報を保護 — ~/.volcengine/config.json は決して読み取らず、access-key、secret-key、session-token を出力に決して含めません

DryRun に関する注意事項

DryRun の検証が成功すると、DryRunOperation が stderr に出力され、終了コード 1（ゼロ以外）が返されます。これは想定された動作です。

output=$(ve <svc> <action> --DryRun true ... 2>&1)
if echo "$output" | grep -q "DryRunOperation"; then
  echo "Parameter validation passed"
fi

---

3. API の検索とパラメーターの取得

API を検索する（サービス名と Action 名を見つける）

Step 1: Service name + Action known? -> Use them directly; skip to "Retrieve parameters"
Step 2: Service name known, Action unknown?
  -> ve <service> 2>&1 | grep -i <keyword>
Step 3: Service name also unknown?
  -> ve 2>&1 | grep -i <service keyword>
Step 4: None of the above work?
  -> python3 scripts/find_api.py <keyword>   (returns Service, Action, Version)

パラメーターを取得する（Action が判明したら）

--help では、名前、型、Required／Optional の簡潔な情報が表示されます。--help --detail を指定すると、すべてのパラメーターについて、詳細な説明、列挙値、制約、使用例が追加されます。これは CLI に含まれる API ドキュメントそのものなので、外部から取得する必要はありません。

状況	コマンド
読み取り専用（Describe/List/Get）	ve <svc> <Action> --help — 通常は名前だけで十分です
書き込み／破壊的操作（Create/Run/Delete…）	ve <svc> <Action> --help --detail — 必須フィールド、ネストされた構造、使用例を確認します
--help を見ても不明な点がある場合	--help --detail を指定します。中国語のテキストを表示するには --lang ZH を追加します
Invalid*／Missing* などのエラーが発生した場合	--help --detail で名前、必須フィールド、範囲を再確認します

ve ecs DescribeInstances --help
ve ecs RunInstances --help --detail
ve ecs RunInstances -h --detail --lang ZH

同じ出力の Parameter Form／--body セクションで、その Action がフラットなパラメーターを受け取るのか、JSON ボディを受け取るのかを確認できます（§4）。

1 つの Action のパラメーターにとどまらない API に関する質問（比較、エラーコードの意味、ページネーションの動作、バッチ版の有無など）には、API Explorer に直接問い合わせる volcengine-api スキルを読み込んでください。

ve コマンド名と API バージョンの関係

• デフォルトバージョン -> ve コマンド = サービス名（例：iam）
• デフォルト以外のバージョン -> ve コマンド = サービス名 + ハイフンを除いたバージョン（例：iam v2021-08-01 -> iam20210801）
• 判断に迷った場合：ve 2>&1 | grep <service> で確認します

CLI のメタデータにない API を呼び出す：--force

ve が unknown service "<svc>" または unknown action を返す一方で、API が存在する場合（ユーザーが提示した、find_api.py が Service／Action／Version を見つけた、またはドキュメントに記載されている場合）は、--force を指定して呼び出します。--force はローカルのメタデータチェックをスキップするため、メタデータに含まれるはずの情報、すなわちバージョンと、CLI が認識していないサービスの場合はエンドポイントを必ず指定してください。

ve newservice DescribeNewResource \
  --version 2024-01-01 \
  --endpoint open.volcengineapi.com \
  --SomeParam value \
  --force

• --version は必須です（--version is required when using --force）。不明なサービスでは、プロファイルまたは VOLCENGINE_ENDPOINT にすでに設定されていない限り、--endpoint も必須です。
• POST API では --method POST を指定します（デフォルトは GET）。JSON ボディには --body '{...}' を指定します（--Param の値と併用できません）。サービスが固定リージョンで署名する場合は --region を指定します。
• --force はフラグです。--force true ではなく --force と指定します。
• パラメーターは検証されません。ユーザーの資料、volcengine-api スキル、または references/extend-apis.md から取得してください。決して推測しないでください。find_api.py が検索するのは Service／Action／Version のみで、パラメーター、メソッド、エンドポイントは返しません。
• §2 の読み取り／書き込み／破壊的操作に関するルールは、リストに記載された Action とまったく同様に適用されます。
• TLS（ログサービス）には --force を使用しないでください。ve には tls OpenAPI コマンドがないため、Product CLI ルーティングテーブルを使って、TLS タスクを ve volclog に振り分けてください。

references/extend-apis.md には、以前ヘルパースクリプトでラップされていた拡張サービス（CDN、DCDN、domain、Flink、GA、IoT、Live、MCDN、Metrics、sec_agent、trademark、VEEN、VKE）のサービスコード／バージョン／エンドポイント／署名リージョンの手順が記載されています。

拡張ヘルパー（クエリとボディを1つのリクエストで送信する場合のみ）

ve --force では、1つの POST で URL クエリパラメーターとリクエストボディを同時に送信できません。VMP Prometheus クエリや Flink GWS など、一部の API ではこれが必要です。その場合に限り、ヘルパーを使用してください。

python3 scripts/call_extend_api.py --list
python3 scripts/call_extend_api.py --api QueryMetrics --params '{"workspace":"<id>","query":"up"}'

ve のアップグレード後、python3 scripts/audit_extend_apis.py を実行してください。新しいメタデータでネイティブに対応できるようになったレシピ／ヘルパー項目が一覧表示されるので、削除できます。

同じ形式の未登録 API 向けに、フリーモード（--service/--version/--query-keys）もあります。認証情報、オプション、登録済み API の一覧については、references/extend-apis.md を参照してください。この会話でユーザーが明示的に選択していない限り、--profile を渡さないでください。

---

4. API 呼び出しの実行

基本形式

VE_CALLER_TYPE=ai_agent VE_CALLER_NAME=<agent-id> VE_SKILL_NAME=<current-volcengine-skill> \
  ve <ServiceCode> <ActionName> --ParamName "value" [system flags]

システムフラグ（--profile、--region、--endpoint、--output、--query、…）は、Action の後に置きます。パラメーターとの順序は問いません。

パラメーターの指定ルール

形式は --help の出力から判断してください。

• フラットなパラメーター形式：--help に個別の --Key type エントリーが表示されている場合（例：ECS、VPC、IAM）、--Key "value" の形式で渡します。
• 配列パラメーター：--help に表示される番号付き CLI 形式（例：--InstanceIds.1 "$instance_id"、--SubnetIds.1 "$subnet_id"）を優先してください。すべてのアクションで JSON 配列文字列が受け付けられるとは限りません。
• JSON 形式：--help に --body '{...}' のみが表示されている場合（例：Redis、CR、その他の POST API）、--body '{...}' の形式で渡します。

# Flat parameters — nested fields use dot notation; arrays use .N index (starting from 1)
ve ecs RunInstances --ZoneId "cn-beijing-a"
ve ecs RunInstances --NetworkInterfaces.1.SubnetId "subnet-xxxx"
ve ecs RunInstances --Tags.1.Key "publish-by" --Tags.1.Value "deploy-skill"

# JSON format (when --help only shows --body)
ve redis CreateDBInstance --body '{"InstanceName":"demo","RegionId":"cn-beijing","ConfigureNodes":[{"AZ":"cn-beijing-a"}],"ShardedCluster":0,"NodeNumber":2,"ShardCapacity":1024,"ShardNumber":1,"EngineVersion":"6.0","SubnetId":"subnet-xxxx","VpcId":"vpc-xxxx","Password":"<secret>","Tags":[{"Key":"publish-by","Value":"deploy-skill"}]}'

出力形式とクエリ

すべての API 呼び出しで --output と --query を使用できます。これらは、JSON に対するその場しのぎの grep／jq の代わりになります。

--output	用途
json（デフォルト）	完全なレスポンス。プログラムで解析する形式です
table / table-num	人が読みやすいリスト。table-num では行番号の列も追加されます。ユーザーにリソース一覧を表示する場合に便利です
text	1行につき1つのプレーンな値。シェル変数に単一フィールドや ID の一覧を格納する場合に便利です
yaml	人が読みやすいネスト形式の詳細情報
off	呼び出しを実行しますが、何も出力しません（レスポンスに依存する --query の評価をスキップします）。レスポンスが本当に不要な呼び出しに限って使用してください。新しいリソース ID がレスポンスにしか含まれない Create*／Run*／Allocate* では使用しないでください

--query には、フォーマット処理の前に完全なレスポンスに対して評価される JMESPath 式を指定します。そのため、パスは Result.（または ResponseMetadata.）から始まります。

# Single field
ve sts GetCallerIdentity --query 'Result.AccountId' --output text

# Project a list for the user
ve ecs DescribeInstances --query 'Result.Instances[].{Id:InstanceId,Name:InstanceName,Status:Status,Zone:ZoneId}' --output table

# Filter, then pick IDs into a shell variable
ids=$(ve ecs DescribeInstances --query "Result.Instances[?Status=='RUNNING'].InstanceId" --output text)

# Length / existence checks
ve vpc DescribeVpcs --query 'length(Result.Vpcs)' --output text

目安：

• エージェントがレスポンスを読む必要がある場合は json のままにし、ユーザーに表示する場合に限って table／yaml に切り替えてください。
• 書き込み／破壊的な呼び出しでは、ResponseMetadata.Error を確認する前に --query で出力を抑制しないでください。失敗時にもエラーオブジェクトは出力されます。
• --query でフィルタリングされるのは出力内容であり、リクエスト内容ではありません。ページネーション（NextToken、PageNumber）は変わりません。

レスポンス形式

// Success
{ "ResponseMetadata": { "RequestId": "..." }, "Result": { ... } }

// Failure
{ "ResponseMetadata": { "Error": { "Code": "...", "Message": "..." } } }

エラー処理

ネイティブの ve <service> <Action> コマンドまたは拡張ヘルパーが失敗した場合、あるいは応答に ResponseMetadata.Error が含まれる場合は、エラーを診断したりユーザーに返答したりする前に、references/common-errors.md をすべて読んでください。部分的な検索結果、一致した行、抜粋だけでは要件を満たしません。ve tosutil／ve arkcli／ve volclog の失敗については、選択した製品スキルとネイティブの子エラー形式に従ってください。

まず、エラーがリクエスト形式、依存関係の不足、アカウントの状態、サービスの有効化、実名確認、購入資格、権限のいずれに関係するかを分類してください。製品固有のエラーについては、以下の該当するサービスノートも読んでください。権限エラー（AccessDenied、NoPermission、RoleNotExist、Forbidden、または STS 関連の失敗）の場合は、volcengine-troubleshooting スキルを有効にし、そのアカウント権限の診断機能を使って根本原因を特定し、ユーザーが問題を解決できるよう案内してください。

CLI の異常や、タスクが完全に解決していない場合は、volcengine-troubleshooting のブロッキングしないフィードバックのガイダンスに従ってください。メインのタスクを続行し、任意のフィードバック依頼は自然な要約の中で行ってください。ユーザーから依頼されたフィードバックは volcengine-feedback に従ってください。利用できない場合は、フィードバックのためにスキルをインストールしたりタスクをやり直したりせず、現在の会話でフィードバックフォームを使用してください。

非同期リソース作成にはポーリングが必要です

VKE クラスター、RDS インスタンス、ECS インスタンスなど、一部のリソースは作成に数分かかります。作成後、リソースが目的のステータスになるまで Describe エンドポイントをポーリングしてから、次の手順に進んでください。

VPC の作成直後にサブリソース（セキュリティグループなど）を作成すると、InvalidVpc.InvalidStatus で失敗する場合があります。サブリソースは順番に（まずサブネット、次にセキュリティグループ）作成するか、数秒待ってから再試行してください。

# General polling pattern: check every 30 s, give up after a deadline, stop on API failure
max_attempts=40   # 40 x 30 s = 20 min; size it to the resource type
for attempt in $(seq 1 "$max_attempts"); do
  if ! cur_status=$(ve <svc> Describe<Resource> --<IdParam> "xxx" --query 'Result.<Path>.Status' --output text 2>&1); then
    echo "describe failed: $cur_status"; break        # classify with common-errors.md, do not keep looping
  fi
  echo "$(date +%H:%M:%S) $cur_status"
  case "$cur_status" in
    Running) break ;;
    Error|Failed|Deleted) echo "resource entered $cur_status"; break ;;
  esac
  [ "$attempt" -eq "$max_attempts" ] && echo "timed out waiting for Running"
  sleep 30
done

Result.<Path> と終端ステータス名は製品ごとに異なります。--help --detail とサービスノートから確認し、Running と決めつけないでください。

---

5. ネイティブ OpenAPI 実行フロー（概要）

1. Set caller metadata for this execution -> verify credentials -> GetCallerIdentity -> confirm region
2. Understand the task: is the user querying or making changes?
3. Locate the API: ve --help first -> find_api.py as fallback -> --force if the metadata lacks it
4. Retrieve parameters: --help, then --help --detail for write/destructive actions
5. Query dependent resources: use Describe*/List* (with --query to pick IDs) to obtain required IDs
6. Read operation -> execute directly and display results (--output table for lists)
   Write operation -> show command -> DryRun (if supported) -> user confirmation -> execute
7. Parse the response and report results to the user

---

6. サービス固有の注意事項

サービス固有の問題が発生した場合は、対応するノートファイルを参照または更新してください。

• 共通エラー：references/common-errors.md
• コンソールログイン手順（ve_login_remote.sh、終了コード、ルール）：references/console-login.md
• Cloud Control API（cloudcontrol）：references/cloudcontrol.md
• ECS：references/ecs.md
• VPC：references/vpc.md
• CR：references/cr.md
• ALB：references/alb.md
• CLB：references/clb.md
• VKE：references/vke.md
• veFaaS：references/vefaas.md
• RDS：references/rds.md
• メッセージキュー：references/mq.md
• ストレージ API：references/storage.md
• オブザーバビリティ：references/observability.md
• DNS／エッジ：references/dns-edge.md
• IAM：references/iam.md
• KMS：references/kms.md
• Redis：references/redis.md
• NAT ゲートウェイ：references/natgateway.md
• EBS：references/ebs.md
• 拡張 API（--force の手順＋クエリ／ボディヘルパー）：references/extend-apis.md