This topic describes how to quickly get started with ve-tos-cli.

Installation

Install via package manager

Install with a shell script

Build from source

Integrate into an AI agent as a skill

Install via npm:

npm install -g ve-tos-cli

Install via pip:

pip install ve-tos-cli

To install on macOS using Homebrew, run the following commands in sequence:

brew tap volcengine/ve-storage-uni-cli https://github.com/volcengine/ve-storage-uni-cli
brew trust volcengine/ve-storage-uni-cli
brew install ve-tos-cli

Install via cargo:

cargo install ve-tos-cli

Quick start

After installation, complete the following steps to perform initialization, credential injection, and the first invocation.

Initialize the tool.

ve-tos-cli config init
ve-tos-cli config set region cn-beijing
ve-tos-cli config set endpoint https://tos-cn-beijing.volces.com
ve-tos-cli config show --output json

Inject access credentials.

export TOS_ACCESS_KEY=<your-access-key-id>
export TOS_SECRET_KEY=<your-secret-access-key>
export TOS_SECURITY_TOKEN=<optional-sts-token>

Run the first command.

ve-tos-cli mb tos://my-bucket --region cn-beijing
ve-tos-cli cp ./local.txt tos://my-bucket/local.txt --dry-run
ve-tos-cli cp ./local.txt tos://my-bucket/local.txt
ve-tos-cli ls tos://my-bucket/prefix/ --output table
ve-tos-cli stat tos://my-bucket/local.txt --output json

Global parameters

Parameter	Environment variable	Description
-P, --profile <PROFILE>	TOS_PROFILE	Sets the profile name in the configuration file. The default name is default.
--config-path <PATH>	TOS_CONFIG_PATH	Specifies the TOML path. The default location is $HOME/.tos/config.toml. This directory also stores the local encryption key used to protect persisted secrets. If the specified path does not exist, the command exits with an error (exit 3) and does not fall back (env /) to the default configuration.
-r, --region <REGION>	-	Overrides the current region setting.
-e, --endpoint <URL>	-	Overrides the current data plane endpoint setting.
--control-endpoint <URL>	-	Specifies the endpoint for control plane operations. This option only applies to TOS. Use it with --account-id or configure it in advance via config set.
--account-id <ID>	-	Specifies the account ID for control plane operations. This option only applies to TOS. Use it with --control-endpoint or configure it in advance via config set.
-o, --output <FORMAT>	TOS_OUTPUT	Sets the output format. The possible values are json, yaml, table, csv, and markdown.
--query <JMESPATH>	-	Filters the output using a JMESPath expression.
--dry-run	-	Previews operations without executing them.
--describe	-	Prints the structured metadata for the command, including the definitions of parameters, descriptions of risks, and API mappings.
-y, --yes	-	Skips interactive prompts and automatically confirms all operations.
--confirm <RESOURCE>	-	Specifies tos://... to confirm critical delete operations with the exact target.
--no-color [<BOOL>]	NO_COLOR	Disables colored output. The default value is true. This is suitable for log collection or terminal environments that do not support ANSI.
-v / -q	-	Sets the output verbosity: -v (--verbose): Enables detailed logs. -q (--quiet): Suppresses non-error output.
--language <en\|zh>	-	Sets the language for help information: en: English. zh: Chinese.

Troubleshooting

Common issues and their resolutions:

Issue	Resolution
Authentication failed (exit 2)	Verify that the TOS_ACCESS_KEY and TOS_SECRET_KEY that you provided are correct. Run ve-tos-cli doctor --check auth for diagnosis.
Configuration missing (exit 3)	If a configuration file that does not exist is specified via --config-path or TOS_CONFIG_PATH, the command exits with error exit 3. Run ve-tos-cli config init and set the region and endpoint.
Control plane command errors	Specify control plane information: via the --control-endpoint and --account-id options. using the environment variable config set.
Deletion blocked	In non‑interactive mode, include --force and an exact target for --confirm <RESOURCE>.
Recursive listing not working	Explicitly specify --recursive-list-mode hierarchical.
Viewing lower-level sub-commands	Run ve-tos-cli <group> --describe --output json to view available sub-commands.

To run a full diagnostic check:

ve-tos-cli doctor --output json

Torch Object Storage