volcengine-cli

Volcengine CLI Skill

通过 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. 初始化（在每次会话开始时运行）

运行身份验证命令，确认凭证可用：

ve sts GetCallerIdentity

成功 -> 告知用户当前账号身份和区域，然后继续执行任务。

切换区域：--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 验证会返回 退出代码 1（非零），并在标准错误中包含 DryRunOperation。这是预期行为：

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