volcengine-cli

Volcengine CLI スキル

ve コマンドを使って Volcengine OpenAPI を呼び出し、Volcengine クラウドリソースを作成・管理します。

---

0. ve CLI をインストールする

システムで ve コマンドを利用できない場合：

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

npm i -g @volcengine/cli

オプション 2：GitHub Releases ダウンロード：https://github.com/volcengine/volcengine-cli/releases

インストールを確認します：ve --version

---

1. 初期化（毎回のセッション開始時に実行）

認証情報が使用可能か確認するため、ID 検証コマンドを実行します：

ve sts GetCallerIdentity

成功 -> 現在のアカウント ID とリージョンをユーザーに伝えてから、タスクを進めます。

リージョンの切り替え：--region フラグと VOLCENGINE_REGION 環境変数では、設定ファイル内のリージョンを上書きできません。リージョンを切り替えるには、ve configure profile --profile <name> を実行します。利用可能なプロファイルは ve configure list で確認できます。

失敗 -> 認証情報が設定されていないか、無効です。次のいずれかの方法を案内します：

オプション 1：環境変数（一時的な使用に推奨）

export VOLCENGINE_ACCESS_KEY="<YOUR_AK>"
export VOLCENGINE_SECRET_KEY="<YOUR_SK>"
export VOLCENGINE_REGION="cn-beijing"

オプション 2：設定ファイル（永続的）

~/.volcengine/config.json が存在しない場合は、ユーザーが入力できる空のテンプレートを作成します：

mkdir -p ~/.volcengine
cat > ~/.volcengine/config.json << 'EOF'
{
  "current": "default",
  "profiles": {
    "default": {
      "name": "default",
      "mode": "ak",
      "access-key": "<YOUR_AK>",
      "secret-key": "<YOUR_SK>",
      "region": "cn-beijing",
      "endpoint": "",
      "session-token": "",
      "disable-ssl": false
    }
  },
  "enableColor": false
}
EOF

~/.volcengine/config.json は絶対に読み取らないでください — このファイルには機密性の高い認証情報が含まれています。空のテンプレートだけを作成し、既存の設定ファイルは読み取らないでください。

---

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>

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

操作の種類に応じて方法を選びます：

操作の種類	方法	理由
読み取り専用（Describe/List/Get）	ve <svc> <action> --help	パラメーターが少なく単純なため、名前だけで十分です
書き込み／破壊的（Create/Run/Delete など）	詳細なドキュメントには scripts/fetch_swagger.py を使用します	パラメーターが多く、ネストした構造があるため、必須フィールド、例、説明が必要です
--help を見ても不明点が残る	scripts/fetch_swagger.py で補足します	パラメーターの意味が不確かな場合はいつでも使用します
Invalid* / Missing* などのエラー	scripts/fetch_swagger.py で再確認します	InvalidParameter、InvalidXxx.NotFound、または MissingParameter が発生した場合は、パラメーター名、必須フィールド、値の範囲を確認します

# Read-only — --help is sufficient
ve ecs DescribeInstances --help

# Write — retrieve full documentation
python3 scripts/fetch_swagger.py --service ecs --action RunInstances

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

• デフォルトバージョン -> ve コマンド = サービスの基本名（例：iam）
• デフォルト以外のバージョン -> ve コマンド = サービス名 + ハイフンを除いたバージョン（例：iam v2021-08-01 -> iam20210801）
• 不明な場合：ve 2>&1 | grep <service> を実行して確認します

Python ヘルパーの使用方法

# Search for an API (when the service name is unknown)
python3 scripts/find_api.py <keyword> [--limit N]

# Get full API parameter documentation (when descriptions/examples are needed)
python3 scripts/fetch_swagger.py --service <ServiceCode> --action <ActionName>

# List all APIs for a service
python3 scripts/fetch_swagger.py --service <ServiceCode> --list

scripts/fetch_swagger.py には必ずベースサービス名を渡してください（例：--service iam。iam20210801ではありません）。スクリプトがバージョンを自動検出します。

---

4. API 呼び出しの実行

基本形式

ve <ServiceCode> <ActionName> --ParamName "value"

パラメーターの渡し方

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

• フラットなパラメーター形式：--help に個別の --Key type エントリーが列挙されている場合（例：ECS、VPC、IAM）→ --Key "value" で渡します
• 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 --Placement.ZoneId "cn-beijing-a"
ve ecs RunInstances --NetworkInterfaces.1.SubnetId "subnet-xxxx"
ve ecs RunInstances --Tags.1.Key "env" --Tags.2.Key "app"

# JSON format (when --help only shows --body)
ve redis CreateDBInstance --body '{"InstanceName":"demo", "RegionId":"cn-beijing", ...}'

レスポンス形式

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

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

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

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

VPC の作成直後にサブリソース（例：セキュリティグループ）を作成すると、InvalidVpc.InvalidStatus エラーが発生することがあります。サブリソースは順番に作成する（先にサブネット、次にセキュリティグループ）か、数秒待ってから再試行してください。

# General polling pattern: check every 30 seconds until the target status is reached
while true; do
  cur_status=$(ve <svc> Describe<Resource> --<IdParam> "xxx" 2>&1 | grep -o '"Status":"[^"]*"')
  echo "$(date +%H:%M:%S) $cur_status"
  echo "$cur_status" | grep -q '"Status":"Running"' && break
  sleep 30
done

---

5. エンドツーエンドの実行フロー（概要）

1. Initialize: verify credentials -> GetCallerIdentity -> confirm region
2. Understand the task: is the user querying or making changes?
3. Locate the API: ve --help first -> Python helpers as fallback
4. Query dependent resources: use Describe*/List* to obtain required IDs
5. Read operation -> execute directly and display results
   Write operation -> show command -> DryRun (if supported) -> user confirmation -> execute
6. Parse the response and report results to the user

---

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

サービス固有の問題が発生した場合は、該当する注意事項ファイルを参照または更新してください。

• ECS：notes/ecs.md
• IAM：notes/iam.md
• Redis：notes/redis.md