tos-cli

Use the tos-cli binary for ByteCloud TOS object storage. Check availability with tos-cli --version before planning commands, and use the first matching executable on PATH unless the user provides an explicit path. Do not run storage operations if the binary is missing.

CLI installation

If tos-cli --version fails and the user wants installation help, suggest one of these installation methods:

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

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

Discovery

tos-cli capabilities --view compact --output json
tos-cli doctor --output json
tos-cli config show --output json

Connection configuration

tos-cli config init does not choose a region, endpoint, or PSM. Configure an endpoint explicitly; a recognizable endpoint may supply the signing region, while a custom endpoint also needs an explicit region. For ByteTOS PSM mode, configure both region and PSM and do not configure endpoint.

tos-cli config set access_key_id <byte-tos-access-key>
tos-cli config set secret_access_key <byte-tos-secret-key>
tos-cli config set endpoint https://your-bytetos-endpoint.example.com
tos-cli config set region cn-beijing
# Alternative PSM mode in another profile (no endpoint in that profile):
tos-cli config set psm-profile.region cn-beijing
tos-cli config set psm-profile.psm toutiao.tos.tosapi

Bare AK/SK keys are stored under the active profile's [profile.tos] credentials section, independently from ve-tos-cli credentials.

Common Commands

tos-cli ls tos://bucket/prefix/ --output json
tos-cli stat tos://bucket/key --output json
tos-cli cp ./file.txt tos://bucket/file.txt --dry-run
tos-cli sync ./dir tos://bucket/prefix/ --dry-run
tos-cli presign tos://bucket/key --expires 3600 --output json

Use tos-cli <command> --help when flags are uncertain.