# Tos CLI

> Use tos-cli for ByteCloud TOS object storage work. Trigger this skill when a user asks an AI agent to inspect, configure, list, upload, download, sync, delete, presign, diagnose, or automate ByteCloud TOS resources with the tos-cli command-line tool.

- Skill: `volcengine/tos-cli` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add volcengine/tos-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/volcengine/tos-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: volcengine (https://skillmd.com/u/volcengine)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/volcengine/tos-cli

---


# 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:

```bash
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

```bash
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.

```bash
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

```bash
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.