volcengine-cli

# Volcengine CLI Skill Use `ve` as the unified entry point for Volcengine OpenAPIs, TOS object operations, Ark product workflows, and TLS log service workflows. ## Agent caller metadata (mandatory) Every `ve` process launched by an Agent must receive these environment variables, including help/version checks, authentication, API calls, retries, polling, and `ve tosutil` / `ve arkcli` / `ve volclog`: | Variable | Required value | | --- | --- | | `VE_CALLER_TYPE` | Always `ai_agent`. | | `VE_CALLER_NAME` | Resolve the actual Agent host identifier from the current runtime environment. This identifies the Agent application, not a model, account, user, or session. | | `VE_SKILL_NAME` | Resolve the `name` in the active Volcengine skill's frontmatter for the workflow executing this command. Use that actual `volcengine-*` name. | Set these values yourself; they are runtime attribution, not credentials or a user setup step. Only `VE_CALLER_TYPE=ai_agent` is fixed. Resolve both the current host and active skill before each execution; neither has a hardcoded default. For example, `codex` is valid only when the current Agent is Codex, and `volcengine-cli` only when that skill owns the current operation. Resolve the values again when the Agent environment or active skill changes. Shared helpers and upstream product CLIs inherit the actual calling Volcengine skill's identity; their executable names or installation directories do not determine it. Supply all three through the tool's process environment or command-local assignments **on every execution**. A new tool call may start a fresh shell, so an earlier `export` is not sufficient. For a multi-command shell block, export all three at the beginning of that block and update the skill name before switching workflows. Put assignments before the executable; these are not CLI flags, API parameters, or fields to add to a request body. For pipelines and `$(...)`, set the variables on the `ve` process itself or export them in that same shell before running the pipeline or expanding the command substitution. Command shape — the Agent must replace both placeholders with values resolved from the actual runtime environment and active skill before execution: ```text VE_CALLER_TYPE=ai_agent \ VE_CALLER_NAME="<agent-id>" \ VE_SKILL_NAME="<current-volcengine-skill>" \ ve ecs DescribeInstances --output json ``` Apply the same environment to any script that launches `ve`, including `install_ve.sh`, `ve_login_remote.sh`, `audit_extend_apis.py`, and `call_extend_api.py`. Their child processes inherit it, including detached login processes; later helper invocations need it again. When running a downloaded installer through a pipe, attach the environment to the shell running the installer, not only to the download command. Preserve required authentication/configuration settings and child CLI arguments; follow the Ark delegation rule below for caller metadata. Command examples elsewhere in this skill and its references show the command syntax; this environment requirement applies to every execution of those examples as well. ### Ark delegation: one set of caller variables For `ve arkcli ...`, supply the three `VE_*` caller variables above. `ve` converts them into the Ark CLI environment, so the Agent must not also add `ARKCLI_CALLER_TYPE`, `ARKCLI_CALLER_NAME`, or `ARKCLI_SKILL_NAME`. Do not copy `ARKCLI_NO_UPDATE_NOTIFIER=1` from standalone Ark examples into the command prefix either; let `ve` manage the delegated process. This applies to Ark authentication, model operations, help, and version commands. ```text VE_CALLER_TYPE=ai_agent \ VE_CALLER_NAME="<agent-id>" \ VE_SKILL_NAME="<current-volcengine-skill>" \ ve arkcli auth status ``` Resolve the placeholders from the actual Agent environment and active Volcengine skill. When reusing a process environment from a standalone Ark invocation, omit the four wrapper-managed variables named above from this invocation. Preserve other product settings and credentials. Standalone `arkcli ...` calls continue to follow the upstream Ark skill's environment rules. ## Product CLI routing **Version requirement:** The [§0 minimum version](#0-install-or-upgrade-the-ve-cli) (`ve >= 1.1.11`) also gates delegation to another CLI, including `ve tosutil`, `ve arkcli` and `ve volclog`. Verify it before delegation. The presence of a proxy command in `--help` alone does not satisfy this requirement. When `ve` is available, prefer **`ve tosutil`**, **`ve arkcli`** and **`ve volclog`**, even when a standalone `tosutil`, `arkcli` or `volclog` is also installed. The TOS command is spelled `tosutil`; `toscli` is a compatibility alias. The existing TOS skill is named `volcengine-tosutil` (not `volcengine-tosutils`). | Task | Entry point | Read before use | | --- | --- | --- | | General cloud resource OpenAPIs | `ve <service> <Action>` | Native API workflow in §§1–5 | | TOS buckets, objects and transfers | `ve tosutil <command>` | Use `volcengine-find-skills` to find `volcengine-tosutil`, install it if missing, and read its instructions | | Ark models, inference, generation, Endpoints, fine-tuning, plans and usage | `ve arkcli <command>` | Download and read the relevant [official Ark skills](https://github.com/volcengine/ark-cli/tree/main/skills) as below | | TLS (日志服务) log search, analysis, ingest, export, Project/Topic and LogCollector collection | `ve volclog <command>` | Use `volcengine-find-skills` to find `volcengine-tls` (or `volcengine-tls-logcollector` for collection), install it if missing, and read its instructions | For TOS, follow the finder's `list` → select exact `volcengine-tosutil` → install if missing → verify installation flow. Load the installed skill and the references it selects before executing. Use its native tosutil command examples, replacing `tosutil ...` with `ve tosutil ...`. For TLS, follow the same finder flow with exact `volcengine-tls`, or `volcengine-tls-logcollector` for LogCollector collection. Those skills write native `volclog ...` examples; run them as `ve volclog ...`. `ve` has no native `tls` OpenAPI command: if `ve volclog` reports an unknown service or suggests `--force`, the `ve` build is older than the version requirement above, so upgrade `ve` instead of adding `--force`. For Ark, select the task skill from the official repository above and install it with `arkcli-shared` and the dependencies its instructions require. These upstream `arkcli-*` names are not entries in the local Volcengine finder catalog; install from the Ark repository directly. For example, model discovery on Codex: ```bash npx --yes skills add https://github.com/volcengine/ark-cli \ --skill arkcli-shared arkcli-auth arkcli-models --agent codex --yes --copy --full-depth npx --yes skills list --agent codex --json ``` Use the actual host's `--agent` and task skill names. Installation is project-scoped by default; add `--global` to both commands only for an intended user-level install. Verify the names and read the installed `arkcli-shared/SKILL.md`, the task skill, and its selected references before execution. If the host cannot load newly installed skills, start a new conversation carrying the original task and completed context, as the finder instructs. Keep product instructions in those skills; this skill only routes to them. `arkcli`, `tosutil` and `volclog` are transparent delegated CLIs: replace only the executable prefix in their examples, keeping all later arguments unchanged. They retain their own authentication, profile, parameters, output, and exit codes. Native API rules such as `--output`, `--query`, `--force`, `--detail`, PascalCase parameters and `--DryRun` do **not** carry over. - Put supported child flags after the child command. `ve --profile <name> arkcli ...` is invalid; `ve arkcli ... --profile <name>` selects an **Ark** profile, not a `ve` profile. - Follow the product skill's authentication, flags, and output handling. Change `tosutil ...` / `arkcli ...` / `volclog ...` into `ve tosutil ...` / `ve arkcli ...` / `ve volclog ...` while keeping all child arguments unchanged. For `ve arkcli`, use only the `VE_*` caller metadata as described in [Ark delegation](#ark-delegation-one-set-of-caller-variables); do not copy the standalone Ark caller/notifier prefix. Keep any required product environment assignments before `ve`. - A working `ve sts GetCallerIdentity` does not prove either child is authenticated. Follow the selected product skill. Help, version, and local preview tasks do not require native API login. - `ve` may refresh its current Console Login session before delegation; that does not translate all `ve` credentials or profile settings into child configuration. A refresh warning alone does not establish that the child command failed. ### Product CLI installation and upgrade `ve` resolves the child from `PATH`, then its managed directory, and installs a missing child on first use from the official CDN with checksum verification. A separate product installation is not a prerequisite. Check only the child needed for the task: ```bash ve tosutil version ve tosutil help ve arkcli --version ve arkcli --help ve volclog --version ve volclog --help ``` Upgrade a managed child with `ve proxycli upgrade tosutil`, `ve proxycli upgrade arkcli` or `ve proxycli upgrade tls-cli`. Management commands take the product ID (`tls-cli` for TLS), while invocation uses the native command name (`ve volclog`). These commands leave external installations on `PATH` to their original package manager; upgrading `ve` alone does not upgrade them. If a child command is missing from `ve --help`, upgrade `ve` first. Product flags and available capabilities follow the resolved child's help. --- ## 0. Install or upgrade the ve CLI Always run the latest release. This skill assumes the current `ve`: device-code `ve login`, `--output`/`--query`, `--force`, `--detail`, and double-dash system flags. There is no support path for older builds — upgrade instead. **Minimum version (mandatory):** Before the first other `ve` command in a task — native OpenAPI calls, login, or product CLI delegation — run `ve version` and require **`ve >= 1.1.11`** (stable releases `1.1.11` or newer). If `ve` is missing, older than `1.1.11`, or its version cannot be verified, install or upgrade with one of the options below and run `ve version` again before continuing. If npm still installs an older version, the configured npm mirror may lag behind; use the CDN installer or GitHub Releases instead. **Option 1: npm (preferred)** ```bash npm i -g @volcengine/cli ``` **Option 2: CDN installer (no Node.js, or npm unreachable)** ```bash curl -fsSL https://cloudcache.volccdn.com/ve/install.sh | sh # or wget -qO- https://cloudcache.volccdn.com/ve/install.sh | sh ``` The same script ships as `scripts/install_ve.sh`. It reads the latest version from the CDN, downloads the archive for the host's OS/CPU, verifies it against the published `SHA256SUMS`, installs to `/usr/local/bin` when writable (else `~/.local/bin`, never `sudo`), removes the macOS quarantine flag, and runs `ve skills update`. `--version <ver>`, `--install-dir <dir>`, `--dry-run` and the `VE_VERSION` / `VE_INSTALL_DIR` / `VOLCENGINE_CLI_DOWNLOAD_BASE_URL` / `VOLCENGINE_CLI_SKIP_SKILLS` variables are documented in its header. Windows: use npm or the release page. **Option 3: GitHub Releases** — https://github.com/volcengine/volcengine-cli/releases **Native OpenAPI capability checks:** `ve login --help` must list `--no-browser`, and `ve ecs DescribeInstances --help` must list `--output` under *System Flags*. If either is missing, upgrade with `npm i -g @volcengine/cli@latest` or rerun the CDN installer, then continue. These checks do not replace the minimum version requirement above. --- ## 1. Native OpenAPI initialization (for API calls) This section applies to `ve <service> <Action>` and extension helpers. For delegated product commands, first follow [Product CLI routing](#product-cli-routing) and the selected product skill. ### CLI system flags Every `ve <service> <Action>` call accepts these **after the Action**, all with two hyphens: | Flag | Purpose | | --- | --- | | `--profile <name>` | Use a configured profile for this call only | | `--region <region>` | Override the region for this call only | | `--endpoint <host>` | Override the endpoint for this call only | | `--lang EN\|ZH` | Display language for this call | | `--version <YYYY-MM-DD>` | API version; metadata default when omitted (required with `--force`) | | `--method GET\|POST` | HTTP method; metadata default, else GET | | `--force` | Skip metadata validation (§3); presence-only, never `--force true` | | `--output <fmt>` / `--query <jmespath>` | Response formatting and projection (§4) | | `--header Name=Value`, `--body '{...}'` | Custom header / raw JSON body | API parameters are PascalCase (`--Region`, `--InstanceIds.1`), system flags are lowercase (`--region`), so they do not normally collide. Only when an API parameter is spelled exactly like a system flag in lowercase (an API with its own `--query` or `--lang` field), write the **system** flag with three hyphens (`---query`) and leave the API parameter with two. Do not use three-hyphen flags anywhere else. CLI management commands (`ve configure ...`, `ve login`, `ve sso login`) and the helper scripts take their own two-hyphen flags as shown by `--help`. ### Profile Selection (fixed for the conversation) `ve` can use different credentials through profiles, but the agent must not choose a profile by itself. - If the user did not explicitly select a profile, use the CLI default resolution: run `ve sts GetCallerIdentity` directly. Do not list all profiles first and choose one yourself. - If the user explicitly selected a profile, keep using that same profile for all later commands in this conversation: `ve ecs DescribeInstances --profile prod`, `python3 scripts/call_extend_api.py --profile prod ...`. - Do not infer the desired profile from profile name, region, list order, recent availability, success rate, or task content. - If the default identity does not match the task risk, or a profile choice is required, tell the user the current default identity, list candidate profile names only, and wait for the user to choose. - Once a profile is fixed for this conversation, do not switch to another profile unless the user explicitly asks to switch. 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 later**: `--region` on a service API call **does** override the region for that single call (the response `Region` changes accordingly), and `VOLCENGINE_REGION` sets the default when the profile has none. What does **not** change is the profile's bound login session/account — a region override only redirects where the request goes, not who you are. Do not switch regions or profiles on your own initiative: only pass `--region` or switch profiles (`ve configure profile --profile <name>`) when the user explicitly asks. Use `ve configure list` only to show candidate profile names; after listing, do not choose a profile yourself. This is separate from the `--region` flag on `ve login` itself, which is required (see below). **Failure** — no usable profile. Default plan: use `ve login` (Console Login). Announce this to the user up front, and tell them they can say "use AK/SK", "use STS token", or "use SSO" to switch. The same plan applies when a previously working session expires **mid-task**: any `ve` command failing with `failed to refresh session token. Please run 've login' to re-authenticate` (or similar refresh-token/session-expired text) is this exact failure, no matter which skill issued the command. The error text tells the human to run `ve login` — do **not** relay that instruction to the user or ask them to run `ve login` in their own terminal; run the Console Login procedure below yourself and only hand the user the sign-in link. Re-login must target the profile that was in use: if a profile was fixed earlier in the conversation, pass it to `start` so both the login and its verification hit that profile — omitting it refreshes `default`, leaves the fixed profile broken, and pollutes the default account context. ### Default: Console Login via `scripts/ve_login_remote.sh` **NEVER call `ve login` directly. ALWAYS use `scripts/ve_login_remote.sh`.** `ve login` is a device-code flow: ve prints a verification URL and user code, then polls until the user approves in a browser on any device. The device code lives only in that ve process, so the helper detaches it (`setsid`) to survive tool-call boundaries, records the URL/code, answers ve's prompts, and verifies the result. Calling `ve login` yourself orphans the process and kills the link. **Before the first `start` of a conversation, read [references/console-login.md](references/console-login.md) completely** — it holds the step-by-step procedure, every exit code, the `start-wait` variant, tuning, and the full list of things that break the flow. The shape is: ```text scripts/ve_login_remote.sh start <region> [profile] # prints URL= CODE= LINK= EXPIRES_IN= NEXT= scripts/ve_login_remote.sh url # same block, never blocks (11 = not yet, 3 = process gone) # hand the user LINK (fallback: URL + CODE), end the turn, wait for "done" scripts/ve_login_remote.sh verify [profile] # 0 ok · 11 still pending · 13 logged in but API unreachable · 10 start over scripts/ve_login_remote.sh abort # on user interrupt / expired code, then start again ``` Region: the one the user named, else `VOLCENGINE_REGION`, else `cn-beijing`. Pass `[profile]` only when the user fixed one earlier, and pass the same value to `start` and `verify`. Invariants that must hold even without reading the reference: - Announce the plan and the off-ramp ("say 'use AK/SK' to switch"), then start — do not present a menu of login methods. - A hung or killed `start` proves nothing: call `url`/`status` before concluding anything; never retry `start`, `abort`, or switch to `nohup` because of it. - Nothing is pasted back by the user; there is no authorization code. Run `verify` when they say they approved. - `verify` exit 13 means the login **worked** and the host cannot reach `open.volcengineapi.com` — do not restart the login. - Use `LINK` exactly as printed; never build `signin.volcengine.com` URLs or reuse one from an earlier process.