Volcengine tosutil Skill

This Skill is designed for the

tosutil

command-line tool of Volcengine Object Storage TOS. It converts user intent into safe, executable, and verifiable

tosutil

operation workflows.

Goal in One Sentence

Convert a request to “perform an operation on TOS” into a

tosutil

command that previews only by default and, when execution is required, outputs structured JSON results + reproducible evidence + diagnostic recommendations.

Inputs and Outputs

Input: target command (such as
```
ls/cp/rm/du/setmeta
```
) + minimum necessary parameters (such as
```
tos://
```
addresses, local paths, and recursive flags) + optional common parameters (
```
endpoint/region/credentials/conf
```
).
Output: a unified JSON protocol (
```
ok/code/message/data/ts
```
) containing
```
preview.shell
```
(a redacted, reproducible command), an execution summary, and
```
advice.code
```
plus
```
next_actions
```
upon failure.

Default Behavior (Lower User Cost + Safety)

By default, only generate a command preview and do not execute it (
```
--run
```
must be explicitly provided to execute).
Destructive commands (such as
```
rm
```
) do not execute by default:
```
--yes
```
(or
```
--assume-yes
```
in legacy mode) must be explicitly provided before they actually run.
Output is redacted by default: AK/SK/Token are never echoed.

When to Use

Invoke this Skill when the user requests any of the following scenarios:

Initialize or update TOS configuration using
```
tosutil
```
Create buckets, list buckets/objects, or query object properties
Upload, download, copy, or batch-delete objects
Calculate object capacity or set object metadata
Analyze issues such as
```
Http status [403]
```
, connectivity failures, or command argument errors
Generate execution plans for advanced commands such as
```
share
```
,
```
set-acl
```
,
```
mount
```
,
```
probe
```
, and
```
netdig
```

Documented Fact Baseline

Based on the

tosutil

documentation set, the following facts can be confirmed:

```
tosutil
```
is a command-line tool for accessing and managing Volcengine Object Storage TOS. It is suitable for batch data processing between local systems and TOS, script integration, and small- and medium-scale data migration.

Core commands include

ls

mkdir

du

mb

cp

setmeta

stat

rm

share

set-acl

, and

mount

Auxiliary commands include

config

help

probe

netdig

hash

fcp

clear

version

ping

connect

traceroute

, and

curl

Initialization configuration supports permanent keys, STS temporary credentials, and anonymous access.
During initialization, use a TOS protocol domain rather than an S3 protocol domain.
```
rm
```
includes a secondary confirmation by default; recursive and batch deletions require an explicit risk assessment.
```
du
```
may take a long time when processing millions of objects, so prefer splitting calculations by directory.

Download and Installation

tosutil

supports Windows, Linux, and macOS. Before using this Skill, it is recommended to download the appropriate version based on the current operating system and chip architecture and set the execute permission.

Official Download Recommendations

Linux amd64: supports direct binary download and execution
macOS amd64 (Intel): supports direct binary download and execution
macOS arm64 (Apple M-series chips): supports direct binary download and execution
Windows 64-bit: download
```
tosutil.exe
```
Official
```
sha256
```
checksum files are also provided. It is recommended to verify the binary's integrity after downloading it
The latest version of
```
tosutil
```
mainly targets Windows, macOS, and Linux amd systems

Installation Commands

Linux:

bash

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/linux/amd64/tosutil
chmod a+x tosutil
sudo mv tosutil /usr/local/bin

macOS Intel:

bash

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/darwin/amd64/tosutil
chmod a+x tosutil
sudo mv tosutil /usr/local/bin

macOS Apple Silicon:

bash

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/darwin/arm64/tosutil
chmod a+x tosutil
sudo mv tosutil /usr/local/bin

Windows:

bash

wget https://m645b3e1bb36e-mrap.mrap.accesspoint.tos-global.volces.com/windows/tosutil -O tosutil.exe

Installation Notes

macOS may block unverified developer applications by default. If the system blocks
```
tosutil
```
on first execution, allow it in the system security settings
After downloading on Linux / macOS, you usually need to run
```
chmod a+x tosutil
```
If you want to run
```
tosutil
```
directly from any directory, move the binary to a directory included in
```
PATH
```
, such as
```
/usr/local/bin
```
If the binary has not been added to
```
PATH
```
, invoke it using an absolute path, for example
```
/absolute/path/to/tosutil version
```
When the binary is not included in
```
PATH
```
, this Skill recommends explicitly specifying its location through
```
--tosutil-binary <absolute-path>
```
to avoid tool-not-found errors

Verification After Installation

If it has been added to

PATH

bash

tosutil version
tosutil config
tosutil ls

If it has not been added to

PATH

bash

/absolute/path/to/tosutil version
/absolute/path/to/tosutil config
/absolute/path/to/tosutil ls

Recommendations:

First use
```
version
```
to verify that the binary is executable
Then use
```
config
```
to confirm the configuration file path
Finally use
```
ls
```
to verify credentials, region, and network connectivity

tosutil

has been added to

PATH

, this Skill can be invoked as follows (the path is relative to the Skill root directory):

bash

python3 scripts/main.py \
  ls \
  --preflight

tosutil

has not been added to

PATH

, this Skill can be invoked as follows:

bash

python3 scripts/main.py \
  ls \
  --tosutil-binary /absolute/path/to/tosutil \
  --preflight

Working Principles

First determine whether the goal is a “read operation” or a “write/delete operation.”
Prefer generating the minimum viable command and avoid combining too many dangerous parameters at once.
For batch upload, download, or copy tasks, confirm concurrency and multipart thresholds before execution.
For deletion tasks, provide pre-check steps and rollback guidance by default; do not bypass confirmation.
When encountering an advanced command whose parameters are not fully confirmed, validate them with
```
tosutil help <command>
```
and never invent parameters.
For non-interactive deletion, use
```
-f
```
, not
```
-y
```
. When cleaning deployment artifacts, prefer deleting constrained prefixes, for example
```
tosutil rm tos://bucket/prefix/ -r -f
```
, to avoid leaving test artifacts behind or accidentally deleting unrelated objects.

Standard Process

1. Scenario Recognition

Classify the user request into one of the following scenarios:

Initialization configuration:
```
config
```
Bucket operations:
```
ls
```
,
```
mb
```
,
```
stat
```
Object transfer:
```
cp
```
Object deletion:
```
rm
```
Object metadata:
```
setmeta
```
Capacity statistics:
```
du
```

Troubleshooting:

version

ls

help

probe

netdig

ping

connect

traceroute

2. Preflight Checks

Execute or suggest the following checks:

bash

tosutil version
tosutil config
tosutil ls

Key checks:

Whether the tool is installed and executable
Whether
```
Endpoint
```
uses a TOS protocol domain
Whether
```
Region
```
matches the target bucket's region
Whether
```
AK/SK
```
or
```
STS Token
```
is present and has sufficient permissions

Whether the output contains

Bucket number is:

Http status [403]

, or

A connection attempt failed

3. Parameter Normalization

Before generating a command, organize the following parameters:

Resource address: local path,
```
tos://bucket
```
, or
```
tos://bucket/prefix
```
Credential mode: permanent keys, STS, or anonymous access
Common parameters:
```
-e
```
,
```
-re
```
,
```
-i
```
,
```
-k
```
,
```
-t
```
,
```
-conf
```
Bucket type:
```
-bt=fns|hns
```
Batch task concurrency:
```
-j
```
Multipart concurrency or multipart task control:
```
-p
```
,
```
-threshold
```
,
```
-ps
```
Result output directory:
```
-o
```

4. Command Generation

Automatically select the command mode based on the resource type:

Local -> TOS: upload
TOS -> local: download
TOS -> TOS: object copy
Single object: single-task mode
Directory or prefix: recursive mode
```
-r
```
Large file: switch to a multipart task according to the threshold

5. Output Validation

Parse the following signals in the execution result:

Success indicators:

successfully

Bucket number is:

Succeed count is:

Task id is:

Permission issue:
```
Http status [403]
```
Network issue:
```
A connection attempt failed
```
Argument issue: command help output, missing required arguments, or invalid path format
Cleanup recommendation: consider
```
clear
```
when a resumable transfer fails

Command Mapping

Initialization Configuration

Permanent keys (recommended):

bash

tosutil config -i <ak> -k <sk> -e <endpoint> -re <region>

endpoint

and

region

can be found in “Appendix: Regions and Access Domains.” Prefer the private endpoint; if the private endpoint is unavailable, use the public endpoint.

STS:

bash

tosutil config -i <ak> -k <sk> -t <token> -e <endpoint> -re <region>

Anonymous access:

bash

tosutil config -i= -k= -t= -e <endpoint> -re <region>

Common Bucket and Object Commands

bash

tosutil ls
tosutil mb tos://bucketname
tosutil cp /local/file.txt tos://bucketname/file.txt
tosutil cp tos://bucketname/file.txt /local/file.txt
tosutil rm tos://bucketname/file.txt
tosutil du tos://bucketname
tosutil setmeta tos://bucketname/object.png -meta aaa:bbb#ccc:ddd

Security Strategy

Before deleting an object, determine whether the target is a single object, directory prefix, or bucket-level deletion.
For
```
rm -r
```
,
```
rm -f
```
, batch metadata updates, batch copies, and similar operations, first output an impact-scope description.
If the user only asks to “generate commands,” do not execute them directly by default.
If a high-risk command must be executed, first suggest listing the target objects or performing a
```
dryRun
```
-style validation. If the command does not support
```
dryRun
```
, perform a read-only check first.

Integration Implementation Recommendations

This Skill should be implemented primarily as a “local CLI wrapper layer” rather than by “directly calling the TOS HTTP API,” because the main body of the documentation provides the

tosutil

command interface.

Script Entry (Recommended Subcommand Mode)

Command preview without execution:

bash

python3 scripts/main.py ls --cloud-url tos://bucketname

Execute and return a structured result:

bash

python3 scripts/main.py ls --cloud-url tos://bucketname --preflight --run

High-risk deletion with explicit confirmation:

bash

python3 scripts/main.py rm --cloud-url tos://bucketname/prefix/ --recursive --run --yes

Legacy entry-point compatibility:

bash

python3 scripts/main.py --command ls --cloud-url tos://bucketname

Recommended directory structure:

text

volcengine-tosutil/
├── SKILL.md
├── references/
│   └── doc-survey.md
└── scripts/
    ├── main.py
    ├── models.py
    ├── result_handler.py
    └── tosutil_service.py

Recommended core classes:

```
CommonOptions
```
/
```
CredentialMode
```
: encapsulate permanent keys, STS, anonymous mode, and common parameters
```
TosResource
```
: parse local paths and
```
tos://
```
resources
```
CommandSpec
```
: encapsulate the command name, argument list, risk level, and whether the operation is destructive
```
TosutilRunner
```
: execute
```
tosutil
```
commands consistently and collect exit codes, standard output, and standard error
```
result_handler
```
: parse results, map errors, and organize structured output fields
```
tosutil_service
```
: build commands, run preflight checks, execute operations, redact sensitive data, and validate common parameters

Key Rules

Configuration Rules

```
config
```
writes to a local configuration file, which by default resides at
```
.tosutilconfig
```
under the user's home directory
```
-conf
```
can only point to an existing configuration file path; it does not automatically create a new file
Prefer explicitly specifying
```
region + endpoint
```
to avoid cross-region mistakes

Transfer Rules

```
cp
```
should infer upload, download, or cloud-to-cloud copy based on the source and destination address types
Actual concurrency for batch tasks should be evaluated using both
```
-j
```
and multipart concurrency parameters; do not blindly increase it
For large files and batch tasks, explicitly set thresholds, concurrency, and output directories to facilitate troubleshooting

Statistics Rules

Do not recursively scan the entire bucket by default with
```
du
```
when there are massive numbers of objects
If bucket versioning is enabled, version-related parameters may be added as needed and the statistics scope may be split

Metadata Rules

```
setmeta
```
supports both single-object and batch-prefix modes
Batch mode must explicitly use
```
-r
```
, and the maximum concurrency
```
-j
```
must be limited

Troubleshooting Tips

Permission Issues

If the result contains
```
Http status [403]
```
, first check whether the AK/SK or STS credentials have expired and whether the target bucket/object permissions are sufficient

Network Issues

If the result contains
```
A connection attempt failed
```
, first check the network, proxy, firewall, and
```
Endpoint
```

Argument Issues

If the parameters of an advanced command are uncertain, first execute
```
tosutil help <command>
```

Cleanup Issues

After a resumable transfer or abnormal interruption, consider using
```
clear
```
to clean up record files and attempt cloud-side cleanup

Best Practices

When first taking over an environment, run the
```
version
```
,
```
config
```
, and
```
ls
```
check sequence
Initialization must use a TOS protocol domain
Anonymous access only applies to public-read or public-write scenarios
Split statistics for millions of objects by directory
Start with conservative concurrency for batch tasks and tune it gradually
Keep secondary confirmation and impact-scope explanations for high-risk commands

Interaction Templates

When the User Wants to Upload a File

Confirm the local path, target bucket, and target object name
Determine whether recursive upload is required
Check the configuration and connectivity
Generate the
```
cp
```
command
Return success criteria and troubleshooting points

When the User Wants to Delete a Directory

First confirm the target prefix
First suggest
```
ls
```
to verify the impact scope
Then generate
```
rm -r
```
If the user confirms forced deletion, consider
```
-f
```

When the User Wants to Troubleshoot an Access Failure

Check
```
version
```
Check
```
config
```
Run
```
ls
```
Categorize the diagnosis based on
```
403
```
, connection failure, or argument error

Testing Requirements

Use documented examples as command-construction test samples
Use example outputs as parser snapshot samples
Add unit tests for scenarios including
```
403
```
, network failures, empty configuration, anonymous access, and recursive deletion
Add integration tests for all three directions of
```
cp
```
: upload, download, and cloud-to-cloud copy
Add boundary tests for the batch parameters of
```
rm
```
,
```
setmeta
```
, and
```
du
```

Limitations

This Skill prioritizes the core commands documented in the most detail:
```
config
```
,
```
ls
```
,
```
mb
```
,
```
cp
```
,
```
rm
```
,
```
du
```
,
```
setmeta
```
,
```
stat
```
,
```
help
```
, and
```
version
```
Advanced commands such as
```
share
```
,
```
set-acl
```
,
```
mount
```
,
```
probe
```
,
```
netdig
```
, and
```
curl
```
use an extended adaptation mode
If the parameters of an advanced command are not fully documented in the current reference materials, they must be confirmed through
```
help
```
or supplemental documentation before execution

<br />

Appendix: Regions and Access Domains

Region: indicates the physical location of the TOS data center.
Endpoint: indicates the domain name through which TOS provides external services.

Region Name	Region ID	Endpoint (Private/Public)	S3 Endpoint (Private/Public)
China North 2 (Beijing)	cn-beijing	Private: tos-cn-beijing.ivolces.com; Public: tos-cn-beijing.volces.com	Private: tos-s3-cn-beijing.ivolces.com; Public: tos-s3-cn-beijing.volces.com
China South 1 (Guangzhou)	cn-guangzhou	Private: tos-cn-guangzhou.ivolces.com; Public: tos-cn-guangzhou.volces.com	Private: tos-s3-cn-guangzhou.ivolces.com; Public: tos-s3-cn-guangzhou.volces.com
China East 2 (Shanghai)	cn-shanghai	Private: tos-cn-shanghai.ivolces.com; Public: tos-cn-shanghai.volces.com	Private: tos-s3-cn-shanghai.ivolces.com; Public: tos-s3-cn-shanghai.volces.com
Hong Kong, China	cn-hongkong	Private: tos-cn-hongkong.ivolces.com; Public: tos-cn-hongkong.volces.com	Private: tos-s3-cn-hongkong.ivolces.com; Public: tos-s3-cn-hongkong.volces.com
Asia Pacific Southeast (Johor)	ap-southeast-1	Private: tos-ap-southeast-1.ivolces.com; Public: tos-ap-southeast-1.volces.com	Private: tos-s3-ap-southeast-1.ivolces.com; Public: tos-s3-ap-southeast-1.volces.com
Asia Pacific Southeast (Jakarta)	ap-southeast-3	Private: tos-ap-southeast-3.ivolces.com; Public: tos-ap-southeast-3.volces.com	Private: tos-s3-ap-southeast-3.ivolces.com; Public: tos-s3-ap-southeast-3.volces.com

volcengine-tosutil

NPX Install

Tags

SKILL.md Content (Chinese)

Volcengine tosutil Skill

Goal in One Sentence

Inputs and Outputs

Default Behavior (Lower User Cost + Safety)

When to Use

Documented Fact Baseline

Download and Installation

Official Download Recommendations

Installation Commands

Installation Notes

Verification After Installation

Working Principles

Standard Process

1. Scenario Recognition

2. Preflight Checks

3. Parameter Normalization

4. Command Generation

5. Output Validation

Command Mapping

Initialization Configuration

Common Bucket and Object Commands

Security Strategy

Integration Implementation Recommendations

Script Entry (Recommended Subcommand Mode)

Key Rules

Configuration Rules

Transfer Rules

Statistics Rules

Metadata Rules

Troubleshooting Tips

Permission Issues

Network Issues

Argument Issues

Cleanup Issues

Best Practices

Interaction Templates

When the User Wants to Upload a File

When the User Wants to Delete a Directory

When the User Wants to Troubleshoot an Access Failure

Testing Requirements

Limitations

Appendix: Regions and Access Domains