Volcengine CLI Skill
Create and manage Volcengine cloud resources by calling Volcengine OpenAPIs through the ve command.
0. Install the ve CLI
If the ve command is not available on the system:
Option 1: npm (recommended)
CODEBLOCK0
Option 2: GitHub Releases
Download: https://github.com/volcengine/volcengine-cli/releases
Verify the installation: ve --version
1. Initialization (run at the start of every session)
Run the identity verification command to confirm that credentials are usable:
CODEBLOCK1
Success -> inform the user of the current account identity and region, then proceed with the task.
Switching regions: the --region flag and the VOLCENGINE_REGION environment variable do not override the region in the config file. Switch regions via ve configure profile --profile <name>. Use ve configure list to view available profiles.
Failure -> credentials are not configured or invalid. Guide the user through one of the following:
Option 1: Environment variables (recommended for temporary use)
CODEBLOCK2
Option 2: Config file (persistent)
If ~/.volcengine/config.json does not exist, create an empty template for the user to fill in:
CODEBLOCK3
Never read ~/.volcengine/config.json — the file contains sensitive credentials. Only create an empty template; never read an existing config.
2. Safety Rules (mandatory)
Read/Write Classification
| Level | Operation Types | Behavior |
|---|
| Read-only | Describe\ / List\ / Get\ / Query\ | Execute directly, no confirmation needed |
| Write |
Create\
/ Run\ / Allocate\
/ Attach\ / Associate\
/ Authorize\ | Show the full command and wait for user confirmation |
|
Destructive | Delete\
/ Terminate\ / Release\
/ Revoke\ / Modify\
/ Stop\ / Detach\* | Show command + impact summary;
require user confirmation |
Core Principles
- 1. Default to read-only — unless the user explicitly requests a change, execute in read-only mode
- DryRun first — if a write/destructive operation supports
--DryRun true, run a DryRun to preview the plan, then confirm before executing - Confirm before executing — show the full command for write operations and wait for approval
- Protect credentials — never read
~/.volcengine/config.json; never expose access-key, secret-key, or session-token in output
DryRun Notes
A successful DryRun validation returns exit code 1 (non-zero) with DryRunOperation in stderr. This is expected behavior:
CODEBLOCK4
3. Locate APIs and Retrieve Parameters
Locate the API (find the service name + Action name)
CODEBLOCK5
Retrieve parameters (once the Action is known)
Choose a strategy based on operation type:
| Operation Type | Strategy | Rationale |
|---|
| Read-only (Describe/List/Get) | INLINECODE12 | Few, simple parameters — names alone are sufficient |
| Write/destructive (Create/Run/Delete, etc.) |
scripts/fetch_swagger.py for full docs | Many parameters, nested structures — need required fields, examples, and descriptions |
|
Still unclear after --help | Supplement with
scripts/fetch_swagger.py | Use whenever parameter meaning is uncertain |
|
Errors like Invalid* / Missing* | Recheck with
scripts/fetch_swagger.py | On
InvalidParameter,
InvalidXxx.NotFound, or
MissingParameter, verify parameter names, required fields, and value ranges |
CODEBLOCK6
ve command name and API version relationship
- - Default version -> ve command = base service name (e.g.,
iam) - Non-default version -> ve command =
service name + version without hyphens (e.g., iam v2021-08-01 -> iam20210801) - When in doubt:
ve 2>&1 | grep <service> to confirm
Python helper usage
CODEBLOCK7
Always pass the base service name to scripts/fetch_swagger.py (e.g., --service iam, not iam20210801) — the script auto-detects the version.
4. Execute API Calls
Basic Format
CODEBLOCK8
Parameter Passing Rules
Determine the format from --help output:
- - Flat parameter format:
--help lists individual --Key type entries (e.g., ECS, VPC, IAM) -> pass with INLINECODE32 - JSON format:
--help only shows --body '{...}' (e.g., Redis, CR, and other POST APIs) -> pass with INLINECODE35
CODEBLOCK9
Response Format
CODEBLOCK10
Async Resource Creation Requires Polling
Some resources (VKE clusters, RDS instances, ECS instances, etc.) take several minutes to create. After creation, poll the Describe endpoint until the resource reaches the desired status before proceeding.
Creating sub-resources (e.g., security groups) immediately after VPC creation may fail with InvalidVpc.InvalidStatus. Create sub-resources sequentially (subnet first, then security group), or wait a few seconds and retry.
CODEBLOCK11
5. End-to-End Execution Flow (Summary)
CODEBLOCK12
6. Service-Specific Notes
Consult or update the corresponding notes file when encountering service-specific issues:
Volcengine CLI 技能
通过 ve 命令调用火山引擎 OpenAPI 创建和管理火山引擎云资源。
0. 安装 ve CLI
如果系统上未安装 ve 命令：
选项 1：npm（推荐）
bash
npm i -g @volcengine/cli
选项 2：GitHub Releases
下载地址：https://github.com/volcengine/volcengine-cli/releases
验证安装：ve --version
1. 初始化（每次会话开始时运行）
运行身份验证命令以确认凭证可用：
bash
ve sts GetCallerIdentity
成功 -> 告知用户当前账户身份和区域，然后继续执行任务。
切换区域：--region 标志和 VOLCENGINE_REGION 环境变量不会覆盖配置文件中的区域。通过 ve configure profile --profile <名称> 切换区域。使用 ve configure list 查看可用配置。
失败 -> 凭证未配置或无效。引导用户执行以下任一操作：
选项 1：环境变量（临时使用推荐）
bash
export VOLCENGINEACCESSKEY=<您的AK>
export VOLCENGINESECRETKEY=<您的SK>
export VOLCENGINE_REGION=cn-beijing
选项 2：配置文件（持久化）
如果 ~/.volcengine/config.json 不存在，创建一个空模板供用户填写：
bash
mkdir -p ~/.volcengine
cat > ~/.volcengine/config.json << EOF
{
current: default,
profiles: {
default: {
name: default,
mode: ak,
access-key: <您的AK>,
secret-key: <您的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. 默认只读 — 除非用户明确要求更改，否则以只读模式执行
- 先 DryRun — 如果写入/破坏性操作支持 --DryRun true，先运行 DryRun 预览计划，确认后再执行
- 执行前确认 — 显示写入操作的完整命令并等待批准
- 保护凭证 — 切勿读取 ~/.volcengine/config.json；切勿在输出中暴露 access-key、secret-key 或 session-token
DryRun 说明
成功的 DryRun 验证返回退出码 1（非零），并在 stderr 中包含 DryRunOperation。这是预期行为：
bash
output=$(ve <服务> <操作> --DryRun true ... 2>&1)
if echo $output | grep -q DryRunOperation; then
echo 参数验证通过
fi
3. 定位 API 并获取参数
定位 API（查找服务名称 + 操作名称）
步骤 1：已知服务名称和操作名称？ -> 直接使用；跳转到获取参数
步骤 2：已知服务名称，未知操作名称？
-> ve <服务> 2>&1 | grep -i <关键词>
步骤 3：服务名称也未知？
-> ve 2>&1 | grep -i <服务关键词>
步骤 4：以上均无效？
-> python3 scripts/find_api.py <关键词>
获取参数（确定操作名称后）
根据操作类型选择策略：
| 操作类型 | 策略 | 理由 |
|---|
| 只读（Describe/List/Get） | ve <服务> <操作> --help | 参数少且简单 — 仅名称即可 |
| 写入/破坏性（Create/Run/Delete 等） |
scripts/fetch_swagger.py 获取完整文档 | 参数多，结构嵌套 — 需要必填字段、示例和描述 |
|
--help 后仍不清楚 | 补充使用 scripts/fetch_swagger.py | 参数含义不确定时使用 |
|
出现 Invalid / Missing 错误 | 使用 scripts/fetch_swagger.py 重新检查 | 遇到 InvalidParameter、InvalidXxx.NotFound 或 MissingParameter 时，验证参数名称、必填字段和取值范围 |
bash
只读 — --help 足够
ve ecs DescribeInstances --help
写入 — 获取完整文档
python3 scripts/fetch_swagger.py --service ecs --action RunInstances
ve 命令名称与 API 版本关系
- - 默认版本 -> ve 命令 = 基础服务名称（例如 iam）
- 非默认版本 -> ve 命令 = 服务名称 + 不含连字符的版本（例如 iam v2021-08-01 -> iam20210801）
- 不确定时：ve 2>&1 | grep <服务> 确认
Python 辅助工具使用
bash
搜索 API（当服务名称未知时）
python3 scripts/find_api.py <关键词> [--limit N]
获取完整 API 参数文档（需要描述/示例时）
python3 scripts/fetch_swagger.py --service <服务代码> --action <操作名称>
列出服务的所有 API
python3 scripts/fetch_swagger.py --service <服务代码> --list
始终将基础服务名称传递给 scripts/fetch_swagger.py（例如 --service iam，而不是 iam20210801）— 脚本会自动检测版本。
4. 执行 API 调用
基本格式
bash
ve <服务代码> <操作名称> --参数名 值
参数传递规则
根据 --help 输出确定格式：
- - 扁平参数格式：--help 列出单个 --键 类型 条目（例如 ECS、VPC、IAM）-> 使用 --键 值 传递
- JSON 格式：--help 仅显示 --body {...}（例如 Redis、CR 和其他 POST API）-> 使用 --body {...} 传递
bash
扁平参数 — 嵌套字段使用点号表示法；数组使用 .N 索引（从 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 格式（当 --help 仅显示 --body 时）
ve redis CreateDBInstance --body {InstanceName:demo, RegionId:cn-beijing, ...}
响应格式
json
// 成功
{ ResponseMetadata: { RequestId: ... }, Result: { ... } }
// 失败
{ ResponseMetadata: { Error: { Code: ..., Message: ... } } }
异步资源创建需要轮询
某些资源（VKE 集群、RDS 实例、ECS 实例等）需要几分钟才能创建完成。创建后，轮询 Describe 端点直到资源达到所需状态，然后再继续。
创建 VPC 后立即创建子资源（例如安全组）可能会失败并显示 InvalidVpc.InvalidStatus。按顺序创建子资源（先子网，后安全组），或等待几秒后重试。
bash
通用轮询模式：每 30 秒检查一次，直到达到目标状态
while true; do
cur_status=$(ve <服务> Describe<资源> --
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.
