ve-adrive-cli

Use ve-adrive-cli for Volcengine ADrive. Resolve one executable before planning commands and use that exact path for the whole task:

1. Use an explicit executable path supplied by the user.
2. Otherwise use command -v ve-adrive-cli and verify it with --version.
3. In a ve-storage-uni-cli source checkout, fall back to packaging/cargo/ve-adrive-cli/target/release/ve-adrive-cli when executable.

Do not run storage operations if the binary is missing or cannot be verified.

CLI installation

If ve-adrive-cli --version fails and the user wants installation help, use one of the documented distribution channels:

cargo install ve-adrive-cli
npm install -g ve-adrive-cli
pip install ve-adrive-cli
brew tap volcengine/ve-storage-uni-cli https://github.com/volcengine/ve-storage-uni-cli
brew install ve-adrive-cli
winget install ve-adrive-cli
curl -fsSL https://github.com/volcengine/ve-storage-uni-cli/releases/latest/download/install.sh | sh -s -- ve-adrive-cli

For developers working from a ve-storage-uni-cli source checkout, build and verify the dedicated artifact instead:

cargo build --release --manifest-path packaging/cargo/ve-adrive-cli/Cargo.toml
./packaging/cargo/ve-adrive-cli/target/release/ve-adrive-cli --version

Only copy a verified artifact onto PATH when installation is explicitly in scope. Do not substitute another ADrive, TOS, or general cloud CLI.

Read references/safety.md before commands that write, delete, move, overwrite, sync, change config, or expose identifiers/URLs.

Discovery

Start read-only. Resolve and verify the executable first, then inspect the selected Profile. Keep full capability discovery conditional because its compact JSON output is large; use it only when command support is uncertain:

ve-adrive-cli --version
ve-adrive-cli config show --output json
ve-adrive-cli --profile default --auth-mode oauth auth status --output json
ve-adrive-cli --profile default --auth-mode oauth doctor --check auth --output json
ve-adrive-cli capabilities --view groups --output json  # only when needed

Do not interpret an unset default auth_mode as proof that OAuth credentials are missing. Before the Profile selects a mode, a generic doctor falls back to AK/SK and can produce an irrelevant missing-key warning. Use explicit OAuth status and Auth Doctor during setup; run the generic Doctor after configuration.

Connection configuration

ADrive has independent Resource and OAuth Authorization Server endpoints. Resource commands require an explicit endpoint; a recognizable IDS endpoint may supply region, while a custom endpoint also needs an explicit region. New OAuth logins additionally require an explicit Auth endpoint. The Resource and Auth endpoints must use different origins.

Endpoint values without a scheme default to https://; dotless service names with numeric ports, such as resource:9000, are treated as hosts. Resource endpoints with an explicit non-HTTP(S) scheme are rejected before any request.

Configure AK/SK only when the user selects that mode. Never print the supplied credentials or read them back as plaintext:

ve-adrive-cli config set auth_mode aksk
ve-adrive-cli config set access_key_id <adrive-access-key>
ve-adrive-cli config set secret_access_key <adrive-secret-key>
ve-adrive-cli config set region cn-beijing
ve-adrive-cli config set endpoint https://ids-cn-beijing.volces.com

Bare AK/SK keys are stored under the active profile's [profile.adrive] credentials section, independently from both TOS command surfaces.

Authentication modes

ADrive supports aksk, oauth, and unified. Mode precedence is --auth-mode > [profile.adrive].auth_mode > ADRIVE_AUTH_MODE > aksk.

Use AK/SK when the user explicitly requests it:

ve-adrive-cli ls adrive://<instance-id> --output json

Unified selects the same-name externally managed profile and ignores local AK/SK and OAuth credentials. The storage CLI does not modify Unified login state; use ve login and ve logout:

ve-adrive-cli config set auth_mode unified
ve login
ve-adrive-cli doctor --check auth --output json
ve-adrive-cli ls adrive://<instance-id> --output json

OAuth login

Default to OAuth for a user's cloud drive. When the user asks to set up or log in, configure the selected Profile once so later Resource commands stay short. For normal public ADrive, require only the Instance ID and use:

• Auth base URL: https://<instance-id>.idsauth.volces.com
• Resource base URL: https://idsapi.volces.com
• Resource signing region: cn-beijing

The Auth host is Instance-scoped. The Resource host is shared; the CLI appends /v1/instances/<instance-id>/... to Resource requests.

The signing region is a CLI connection input, not a discovered statement about where the Instance is physically deployed.

Persist the non-secret connection settings in the selected Profile before the first login. config set writes one key at a time, so set every field once and then re-read the Profile to catch a partial setup. If the user explicitly requests a non-persistent invocation, pass the same values as command or environment overrides instead:

ve-adrive-cli config set auth_mode oauth
ve-adrive-cli config set auth_endpoint https://<instance-id>.idsauth.volces.com
ve-adrive-cli config set endpoint https://idsapi.volces.com
ve-adrive-cli config set region cn-beijing
ve-adrive-cli config set default_instance <instance-id>
ve-adrive-cli config show --output json

Pass only the base URL to --auth-endpoint; the CLI appends paths such as /v1/oauth/device_authorization and /v1/oauth/token. Keep the foreground process running while the user completes Device Authorization:

ve-adrive-cli auth login --output json

Login is a mixed-stream foreground operation: authorization instructions arrive as plain text on stderr, while the final result uses the selected stdout format. Read stderr incrementally, preserve the original process/session, and wait for that same process after authorization; do not start a second login.

Forward the complete verification URL exactly as the CLI returns it. The CLI accepts HTTPS URLs, plus HTTP only for loopback development URLs, and rejects userinfo or unsafe schemes before printing. The URL is supplied by the Authorization Server and its UI origin can differ from the Auth API origin. The CLI may not print a separate User Code; only display one separately when it is explicitly present in the returned URL. Never print Device Codes, Access Tokens, Refresh Tokens, authorization headers, or stored secret material.

After authorization, require the original process to succeed, then verify explicit OAuth status and Auth Doctor. Status plus Doctor validate local credential readiness; finish a real end-to-end check with a harmless Resource command such as ls. A generic Doctor is primarily diagnostic, and even its live-network check only establishes endpoint reachability rather than business API success.

Treat an OAuth status as reusable only when ready is true and its instance_id matches the requested Instance. Otherwise start a new explicit login for the requested Instance.

OAuth login stores returned identity metadata such as user_id with the selected profile. It does not decode identity from a Token.

If a login or refresh response does not provide user_id, run ve-adrive-cli --auth-mode oauth auth login --instance instance-id again with the OAuth-authorized Instance ID, or pass --owner-id explicitly for the owner-aware operation.

If Auth returns 404, verify the Instance ID and documented Auth base URL. If a Resource request rejects a Token, inspect explicit OAuth status, requested Instance, and Resource endpoint before deciding whether to log in again. Do not use the Auth endpoint as the Resource endpoint.

Space listing and ownership

After Profile setup, reuse its selected mode, Resource Server, and region. Do not repeat connection flags on normal Resource commands:

# Spaces owned by the logged-in user.
ve-adrive-cli ls adrive://<instance-id> --owner-type user --output json

# Spaces owned by groups available to the logged-in user.
ve-adrive-cli ls adrive://<instance-id> --owner-type group --output json

For a deliberate non-persistent mode override, the equivalent commands are ve-adrive-cli --auth-mode oauth ls adrive://instance-id and ve-adrive-cli --auth-mode oauth ls adrive://instance-id --owner-type group. Normal Profile-based use should keep the shorter commands above.

For each owner collection, read data.is_truncated and data.next_marker. When truncated, pass the opaque marker to the next request and repeat until is_truncated is false; never construct or modify a marker:

ve-adrive-cli ls adrive://<instance-id> --owner-type user \
  --max-keys 1000 --marker '<previous-next-marker>' --output json

Run the same loop for --owner-type group. Count any separately returned data.root_space once across all pages. Report user-owned and group-owned counts separately before the total.

After discovering Spaces, list each Space root with the same pagination loop:

ve-adrive-cli ls adrive://<instance-id>/<space-id>/ \
  --max-keys 1000 --output json

For creation, OAuth user-owned Spaces default --owner-id to the stored user_id; group-owned Spaces always require an explicit owner ID:

ve-adrive-cli crt adrive://<instance-id>/personal --owner-type user

ve-adrive-cli crt adrive://<instance-id>/team \
  --owner-type group --owner-id <group-id>

Instance creation retains the authentication-mode-specific service defaults:

# AK/SK defaults to arkclaw.
ve-adrive-cli crt adrive://<instance-name>

# OAuth defaults to paas after the Profile selects OAuth.
ve-adrive-cli crt adrive://<instance-name> --service-type paas

File and folder commands

Use the mode, Resource endpoint, and region already stored in the selected Profile. Add connection flags only for a deliberate one-off override:

ve-adrive-cli ls adrive://<instance-id>/<space-id>/path/ --output json

ve-adrive-cli stat \
  adrive://<instance-id>/<space-id>/path/file --output json

ve-adrive-cli cp ./file.txt \
  adrive://<instance-id>/<space-id>/file.txt --dry-run

ve-adrive-cli sync ./dir \
  adrive://<instance-id>/<space-id>/prefix/ --recursive --dry-run

ve-adrive-cli mkdir \
  adrive://<instance-id>/<space-id>/new-folder

Use ve-adrive-cli <command> --help when non-connection flags are uncertain.