Docs

Torch Object Storage

tosutil

Quick start

This topic describes how to quickly get started with tosutil, including its prerequisites and initialization process.

Prerequisites

You have installed tosutil. For instructions, see Downloading and installing tosutil.

You have obtained the region and endpoint of the TOS server that will execute your command. For more information on TOS regions and endpoints, see Regions and endpoints.

You have obtained the access key ID (AK) and secret access key (SK). For instructions on how to view the AK and SK, see Viewing the Access Key ID and Secret Access Key.

Notes

The command examples in this guide apply exclusively to Linux and macOS systems. For Windows command syntax, see Command syntax.

Step 1: Initialize tosutil

(Optional) When using tosutil on Linux or macOS, run this command to add execute permission.

Skip this step if you are using tosutil on Windows.

chmod +x tosutil

Use the config command to initialize tosutil. Adjust the command according to your scenario.

Using long-term access credentials

# -i = account/sub-user access key
# -k = account/sub-user secret key
# -e = endpoint
# -re = region
./tosutil config -i <access key> -k <secret key> -e <endpoint> -re <region>

Using temporary access credentials

# -i = temporary access key
# -k = temporary secret key
# -t = temporary security token
# -e = endpoint
# -re = region
./tosutil config -i <access key> -k <secret key> -t <security token> -e <endpoint> -re <region>

warning

Make sure that the endpoint you provide follows the TOS protocol. Endpoints that follow the S3 protocol are not supported. For more information on TOS regions and endpoints, see Regions and endpoints.

After you configure the credentials via the config command, a .tosutilconfig file will be generated in your operating system's home directory. On macOS/Linux, this directory is ~, and on Windows, it is C:\Users\<username>. This file stores all tosutil configurations. To prevent security issues caused by key leakage, tosutil automatically encrypts your information.

Anonymous access

tosutil supports anonymous access to TOS. When accessing a bucket anonymously, you can retrieve publicly readable data and write data to buckets configured with public write permissions.

In this case, you do not need to specify access credentials when using the config command for initial configuration. Simply set the relevant parameters to -i=, -k=, and -t=.

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

Step 2: Check version and connectivity

After initializing tosutil, you can use the following command to check its version and connectivity.

Use the version command to check the tool's version.

# Check version
./tosutil version

The command returns an output containing text similar to the following:

tosutil version: v1.1.0
operating system: darwin, arch: amd64

Use the ls command to test for connectivity.

# This commands returns a list of the buckets owned by the current account
./tosutil ls

The command returns an output containing text similar to the following:

Start at 2022-10-27 09:29:45.79638 +0000 UTC
Bucket CreationDate Location
tos://db-storage 2022-07-28T06:53:37Z cn-beijing

tos://tosutil 2022-07-05T09:40:35Z cn-beijing

Bucket number is: 2

tip

You can then judge the configuration result based on the output of the ls command.

If the output contains Bucket number is:, then the configuration is correct.

If the output contains Http status [403], then the access credentials that you provide are incorrect or lack the necessary permissions.

If the output contains A connection attempt failed, it means that TOS cannot connect. Please check your network connection.

Step 3: Use tosutil

This section introduces the most common commands for creating buckets and uploading, downloading, and deleting objects using tosutil.

Run this command to create a bucket named bucketname.

# Create a bucket
./tosutil mb tos://bucketname

tip

The default region for creating buckets is the region set during initialization. To create a bucket in a different region, use the -re command. For more information, see Common parameters.

Run this command to upload the file.txt object to the bucketname bucket.

# Upload an object
./tosutil cp /temp/file.txt tos://bucketname/file.txt

Run this command to download the file.txt object from the bucketname bucket to your local device.

# Download an object
./tosutil cp tos://bucketname/file.txt /temp/file.txt

Run this command to delete the file.txt object from the bucketname bucket.

# Delete an object
./tosutil rm tos://bucketname/file.txt

warning

When you use the rm command to delete an object, tosutil prompts you to confirm with y/n. To force the deletion, add the -f parameter. See the rm command documentation for more information.

Run this command to upload the test_folder folder to the bucketname bucket.

# Upload a folder
./tosutil cp /temp/test_folder tos://bucketname -r

Run this command to download the test_folder folder from the bucketname bucket to your local device.

# Download a folder
./tosutil cp tos://bucketname/test_folder/ /temp/ -r

Run this command to delete the test_folder folder from the bucketname bucket.

# Delete a folder
./tosutil rm tos://bucketname/test_folder/ -r

Help documentation

tosutil includes built-in help documentation. You can use the help command to view it.

# View help information
./tosutil help

The help documentation is available in both Chinese and English. Use the following command to switch the language of the documentation:

# Switch help language
vim ~/.tosutilconfig
# Options for helpLanguage：
# Chinese
# English

Last updated: 2025.12.17 18:33:42