Imported from volcengine/volcengine-agent-toolkit (
skills/core/volcengine-cli/SKILL.md) via skills.sh. Install upstream withnpx skills add volcengine/volcengine-agent-toolkit --skill volcengine-cli. Copyright stays with the author (MIT).
Volcengine CLI Skill
Credential safety (mandatory)
ve finds its credentials by itself. You never need to see them, in whole or in part.
- Never print or dump environment variables: no
env,printenv,set,export -p,declare -x,echo $VOLCENGINE_*, no reading/proc/*/environ. "Pre-flight" and "environment" checks are no exception. - Never read
~/.volcengine/config.jsonor other credential/login-cache files. - No self-made redaction: do not pipe the above through
sed,grep,grep -v,awkorcutto mask values, and do not print a prefix, suffix or length of a secret. Such filters are easy to get wrong and leak it. - The only credential check is
ve sts GetCallerIdentity. Success = usable. Failure = follow references/auth.md; do not inspect or edit the credentials to debug it. - Never put an AccessKey, SecretKey or session token in a reply, file or log.
Agent caller metadata (mandatory)
Prefix every ve execution (help, version, login, API calls, retries, polling, product CLIs) and every scripts/ helper with three variables:
VE_CALLER_TYPE=ai_agent VE_CALLER_NAME="<agent-id>" VE_SKILL_NAME="<current-volcengine-skill>" \
ve ecs DescribeInstances --output json
| Variable | Value |
|---|---|
VE_CALLER_TYPE |
Always ai_agent. |
VE_CALLER_NAME |
Your own Agent product name, such as codex or claude-code. You already know which Agent you are: write it directly, and do not look at environment variables or host information to find it. It names the Agent application, not a model, account or user. |
VE_SKILL_NAME |
The frontmatter name of the Volcengine skill whose workflow runs the command; volcengine-cli when this skill owns it. |
- Write the values yourself; never pass the placeholders or copy another Agent's name.
- A tool call may start a fresh shell: repeat the prefix every time. In pipelines and
$(...)it must reach theveprocess itself. - These are assignments, not flags or request fields. Never add
VOLCENGINE_SAFETY_*here. ve arkcli: these three only, noARKCLI_*variables. More cases: references/env-vars.md.
Next: Product CLI routing and Native OpenAPI essentials. If you cannot see both headings below, your tool cut them out; before your first ve call run:
sed -n '/^## Product CLI routing/,/^## References/p' <path-of-this-SKILL.md>
Product CLI routing
| Task | Entry point | Read before use |
|---|---|---|
| Cloud resource OpenAPIs | ve <service> <Action> |
locate-api.md, execute-api.md |
| TOS buckets, objects and transfers | ve tosutil <command> |
product-cli.md, then skill volcengine-tosutil |
| Ark models, inference, generation, endpoints, fine-tuning, plans, usage | ve arkcli <command> |
product-cli.md, then the official Ark skills |
| TLS (日志服务) search, analysis, ingest, export, LogCollector | ve volclog <command> |
product-cli.md, then volcengine-tls / volcengine-tls-logcollector |
- Prefer the
veproxy even when a standalonetosutil,arkcliorvolclogis installed.veinstalls a missing child on first use. - Replace only the executable prefix of the product skill's examples (
tosutil ...→ve tosutil ...); keep every later argument. Child flags go after the child command. - Delegated CLIs keep their own authentication, profiles, flags, output and confirmation rules. Native rules (
--output,--query,--force,--DryRun, the safety policy and its--yesretry) do not carry over, and a workingve sts GetCallerIdentitydoes not prove the child is authenticated. vehas no nativetlsservice: never use--forcefor TLS; an unknown-service answer fromve volclogmeansveis too old.
Native OpenAPI essentials
Details and examples: locate-api.md and execute-api.md.
- Find the API:
ve <service> 2>&1 | grep -i <keyword>for the Action,ve 2>&1 | grep -i <keyword>for the service, thenpython3 scripts/find_api.py <keyword>. A non-default API version is a separate command (iamv2021-08-01 →iam20210801). - Parameters:
ve <svc> <Action> --help; add--detailfor write/destructive actions or afterInvalid*/Missing*errors. Never guess parameter names. - Shape: API parameters are PascalCase (
--InstanceIds.1 i-xxx,--Tags.1.Key k), system flags are lowercase and follow the Action (--region,--profile,--output,--query). When--helpshows only--body, pass one JSON body:--body '{...}'. - Output: keep the default
jsonfor your own reading;--query '<JMESPath from Result.>'with--output textto capture IDs,--output tableto show lists to the user. Do not use--output offonCreate*/Run*/Allocate*. - API missing from the CLI metadata (
unknown service/unknown action):--forcewith--version(and--endpointfor an unknown service); recipes in extend-apis.md. - Async resources: poll the
Describe*call with a deadline until the target status; take status names from--help --detailand the service note. - DryRun: a successful
--DryRun trueexits 1 withDryRunOperationin stderr; that is the pass signal.
References
If the text above this heading shows a truncated marker, the two sections before it were cut: run sed -n '/^## Product CLI routing/,/^## References/p' on this file. Then read the reference for your step.
- Install / upgrade
ve: install.md - Credentials, profiles, login: auth.md; Console Login procedure: console-login.md
- Confirmation modes, safety policy, DryRun: safety.md
- Find the API, parameters,
--force: locate-api.md;--forcerecipes: extend-apis.md, extend-api-params.md; query+body helper: extend-api-helper.md - System flags, parameters,
--output/--query, polling: execute-api.md - Product CLIs: product-cli.md; errors: common-errors.md
- Service notes: alb, clb, cloudcontrol (writes), cr, dns-edge, ebs, ecs, iam, kms, mq, natgateway, observability, rds, redis, storage, vefaas, vke, vpc
Mandatory rules
- Version — before any other
vecommand in a task, runve versionand requireve >= 1.1.11, also for product CLI delegation. Missing or older: references/install.md. - Read-only by default — change resources only when the user explicitly asks.
- Leave the safety policy alone — unless the user explicitly asks to change the policy itself, never run
ve configure safety-policy enable|disable|add|remove, never read or edit~/.volcengine/safety-policy.json, never setVOLCENGINE_SAFETY_POLICY_ENABLED,VOLCENGINE_SAFETY_POLICY_RULESorVOLCENGINE_SAFETY_SKIP_CONFIRM. - Confirmation mode — before the first native call of a conversation (including
ve sts GetCallerIdentity) runve configure safety-policy show, then read references/safety.md before any write or destructive call.- JSON with
"enabled": trueand non-emptyrules: the CLI enforces. Run without--yes.requires confirmation→ ask the user, end the turn, then re-run the identical command once with--yes.blocked by safety policy→ stop; no other route. - Anything else: built-in rules.
Describe*/List*/Get*/Query*run directly.Create*/Run*/Allocate*/Attach*/Associate*/Authorize*→ show the full command and wait for confirmation.Delete*/Terminate*/Release*/Revoke*/Modify*/Stop*/Detach*→ show command and impact; confirmation required. DryRun first when supported.
- JSON with
- Profile and region — never choose or switch them yourself; pass
--profile/--regiononly when the user explicitly selected one, then keep it. - Login — never call
ve logindirectly and never ask the user to run it. Read references/auth.md and usescripts/ve_login_remote.sh, also when a session expires mid-task. - Errors — when a command fails or returns
ResponseMetadata.Error, read references/common-errors.md completely before diagnosing. Permission errors: usevolcengine-troubleshooting.
Native OpenAPI execution flow
1. Caller metadata on every command -> ve version -> ve configure safety-policy show (rule 4)
2. Run `ve sts GetCallerIdentity`. This IS the credential check: do not look at environment
variables or config files. Report identity and region.
3. Is the user querying or changing something?
4. Locate the API: ve <service> | grep -> scripts/find_api.py -> --force if metadata lacks it
5. Parameters: --help; --help --detail for write/destructive actions
6. Dependent IDs: Describe*/List* with --query
7. Read -> execute and show results (--output table for lists)
Write, built-in rules -> show command -> DryRun if supported -> user confirms -> execute
Write, safety policy -> execute -> if blocked or held, follow references/safety.md
8. Parse the response and report
Credential reminder: never run env, printenv, set, export -p or echo $VOLCENGINE_*, with or without a sed/grep filter, and never read ~/.volcengine/config.json. ve sts GetCallerIdentity is the only credential check; if it fails, follow references/auth.md instead of inspecting the credentials.
