volcengine-cli

Files (7)

• LICENSE
• SKILL.md
• ecs.md · notes/
• iam.md · notes/
• redis.md · notes/
• fetch_swagger.py · scripts/
• find_api.py · scripts/

SKILL.md (first lines)

# 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)**
```bash
npm i -g @volcengine/cli
```

**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:

```bash
ve sts GetCallerIdentity
```

**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)
```bash
export VOLCENGINE_ACCESS_KEY="<YOUR_AK>"
export VOLCENGINE_SECRET_KEY="<YOUR_SK>"
export VOLCENGINE_REGION="cn-beijing"
```

**Option 2: Config file** (persistent)

If `~/.volcengine/config.json` does not exist, create an empty template for the user to fill in:

```bash
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
```

> **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
2. **DryRun first** — if a write/destructive operation supports `--DryRun true`, run a DryRun to preview the plan, then confirm before executing
3. **Confirm before executing** — show the full command for write operations and wait for approval
4. **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:

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

---

## 3. Locate APIs and Retrieve Parameters

### Locate the API (find the service name + Action name)

```
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>
```

### Retrieve parameters (once the Action is known)

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples