本章节介绍如何快速使用 ve\-tos\-cli。 ## 安装指引通过包管理器安装 * 使用 npm 安装： ```Shell npm install -g ve-tos-cli ``` * 使用 pip 安装： ```Shell pip install ve-tos-cli ``` * 在 macOS 上使用 Homebrew 安装，依次执行以下命令： ```Plain Text 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 ``` * 使用 cargo 安装： ```Shell cargo install ve-tos-cli ``` Shell 一键安装通过 Shell 脚本一键安装 ve\-tos\-cli。 ```Shell curl -fsSL https://github.com/volcengine/ve-storage-uni-cli/releases/latest/download/install.sh | sh -s -- ve-tos-cli ``` 源码构建通过源码构建安装 ve\-tos\-cli。 ```Shell git clone git@github.com:volcengine/ve-storage-uni-cli.git cd ve-storage-uni-cli cargo build --release --manifest-path packaging/cargo/ve-tos-cli/Cargo.toml ./packaging/cargo/ve-tos-cli/target/release/ve-tos-cli --help ``` 作为 SKILL 集成到 AI-Agent ve\-tos\-cli 可作为 SKILL 集成到 AI Agent。更多信息，请参见[AI-Agent 指南](https://www.volcengine.com/docs/6349/2563187)。 ```Shell # SKILL 地址 https://github.com/volcengine/ve-storage-uni-cli/tree/main/skills/ve-tos-cli ``` ## 快速开始完成安装后，可按以下步骤完成初始化、凭证注入与首次调用验证。

说明

统一采用 tos://bucket/key 格式引用对象存储资源。

1. 初始化配置。 ```Bash 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 ``` 2. 注入访问凭证。 ```Bash export TOS_ACCESS_KEY= export TOS_SECRET_KEY= export TOS_SECURITY_TOKEN= ``` 3. 执行首次调用。 ```Bash 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 ``` ## 全局参数 |参数项 |环境变量 |说明 | |---|---|---| |\-P, \-\-profile |TOS_PROFILE |指定配置文件中的 `profile `名称，默认为 `default`。 | |\-\-config\-path |TOS_CONFIG_PATH |指定 `TOML `配置文件路径，默认为 `$HOME/.tos/config.toml`。

该目录同时存放用于保护落盘密钥的本地加密 `key`。

若显式指定路径但文件不存在，命令将直接报错退出（`exit 3`），不回退（`env /`）至默认配置。 | |\-r, \-\-region |\- |覆盖当前配置的区域（Region）。 | |\-e, \-\-endpoint |\- |覆盖当前配置的数据面 `endpoint `地址。 | |\-\-control\-endpoint |\- |指定控制面 `endpoint `地址，仅 TOS 支持。

需配合 `--account-id` 使用，或提前通过 `config set` 完成配置。 | |\-\-account\-id |\- |控制面操作所需的账户 ID，仅 TOS 支持。

需配合 `--control-endpoint` 使用，或提前通过 `config set` 完成配置。 | |\-o, \-\-output |TOS_OUTPUT |指定输出格式，支持 `json`、`yaml`、`table`、`csv` 和 `markdown` 。 | |\-\-query |\- |使用 `JMESPath ` 表达式对输出结果进行过滤。 | |\-\-dry\-run |\- |预览模式，仅输出待执行操作，不实际执行。 | |\-\-describe |\- |输出命令的结构化元数据，包括参数定义、风险说明及 API 映射信息。 | |\-y, \-\-yes |\- |跳过交互式确认提示，自动确认所有操作。 | |\-\-confirm |\- |通过精确匹配 `tos://...` 资源路径确认删除操作，用于高风险删除场景的二次校验。 | |\-\-no\-color [] |NO_COLOR |禁用彩色输出，默认为 `true`。

适用于日志采集或不支持 ANSI 的终端环境。 | |`-v / -q` |\- |配置输出显示：

* `-v` ：输出详细日志。

* `-q` ：静默模式，仅输出错误信息。 | |\-\-language |\- |指定帮助信息的显示语言：

* `en`：英文。

* `zh`：中文。 | ## 故障速查 * 常见故障排查： |现象 |排查方法 | |---|---| |鉴权失败（exit 2） |1. 确认 `TOS_ACCESS_KEY` 和 `TOS_SECRET_KEY` 已正确配置。

2. 执行 `ve-tos-cli doctor --check auth` 进行诊断。 | |配置缺失（exit 3） |若通过 `--config-path` 或 `TOS_CONFIG_PATH` 指定了不存在的配置文件，运行类命令将报 `exit 3`。

执行 `ve-tos-cli config init` 并设置 `region `和 `endpoint`。 | |控制面命令报错 |需指定控制面相关信息：

* 通过参数 `--control-endpoint` 和 `--account-id` 指定。

* 通过环境变量 `config set` 指定。 | |拒绝删除 |非交互模式下须附加` --force` 及精确的 `--confirm ` 参数。 | |递归并发不生效 |显式指定 `--recursive-list-mode hierarchical`。 | |查看低阶子动作 |执行 `ve-tos-cli --describe --output json` 查看可用子动作。 | * 完整诊断命令： ```YAML ve-tos-cli doctor --output json ```