Common Commands

This page summarizes commonly used US3CLI commands. Command syntax is kept consistent with the CN documentation; only the explanatory text is translated to English. For the most up-to-date option list, you can also run us3cli <command> -h.

Operation	Command	Description
Configuration	config	Manage AccessKey/SecretKey/endpoint and profiles (create/update/delete/switch/view)
Create bucket	mb	Create a bucket
Delete bucket	rb	Delete a bucket (bucket must be empty)
Bucket/object metadata	stat	View bucket metadata or object metadata
Storage usage	du	View bucket storage usage (STANDARD/IA/ARCHIVE)
Upload/Download/Copy	cp	Upload/download/copy files or directories
Incremental sync	sync	Incrementally upload a directory to US3
Streaming upload	rcat	Upload data from stdin (streaming)
Create directory	mkdir	Create an empty directory in a bucket
Streaming download	cat	Download object data to stdout (streaming)
Move	mv	Move files or directories (within the same bucket)
Remove	rm	Delete objects or prefixes
List	ls	List buckets / objects / projects
Signed URL	sign	Generate a download URL for an object
Modify metadata	modify	Modify storage class / mimetype / metadata of objects
Restore archive	restore	Restore ARCHIVE objects to downloadable state
ETag	etag	Calculate ETag for local/stdin/US3 objects
Token: create	create-token	Create a token for operating US3
Token: delete	delete-token	Delete a token
Token: update	update-token	Update a token
Token: describe	describe-token	List/describe tokens
Update	update	Update the CLI version
Version	version	Show CLI version

config

config manages configuration profiles used by other commands.

Syntax


us3cli config [--ls] [--su <profile>] [--rm <profile>] [--cat <profile>] [--encrypt] [--ssl] [--proxy <proxy>]
             [--accesskey <API/Token public key>] [--secretkey <API/Token private key>] [--endpoint <endpoint>]
             [--language <ZH/EN>]

Key options

--ls: list profiles
--su <profile>: switch default profile
--rm <profile>: delete profile
--cat <profile>: print profile content
--encrypt: enable credential encryption
--ssl: use HTTPS
--proxy <proxy>: proxy address
--accesskey, --secretkey, --endpoint: non-interactive profile creation/update
--language: CLI language (ZH/EN)

Config fields

Field	Description
AccessKey	API public key or Token public key
SecretKey	API private key or Token private key
Endpoint	Region endpoint (public or intranet)
encrypt	`true`/`false`
enablessl	`true`/`false`
proxy	`ip:port`
language	`ZH`/`EN`

Example custom config file:


accesskey: "user accesskey"
secretkey: "user secretkey"
endpoint: "ufile.cn-north-02.ucloud.cn"
encrypt: "false"
enablessl: "false"
proxy: "http://ip:port or https://ip:port"
language: "EN"

mb

Create a bucket.

Syntax


us3cli mb us3://<bucket> [--acl <private|public>] [--region <region>] [--projectid <projectid>]

Examples


# Interactive
./us3cli mb us3://us3cli-test

# Non-interactive
./us3cli mb us3://us3cli-test --acl private --region cn-bj --projectid org-xxxxxx

Note: If your bucket is not under the default project, most bucket operations require --projectid.

rb

Delete a bucket (bucket must be empty).

Syntax


us3cli rb us3://<bucket> [--projectid <projectid>] [--force]

Example


./us3cli rb us3://bucket1

stat

View bucket metadata or object metadata.

Syntax


us3cli stat us3://<bucket>[/<key>] [--projectid <projectid>]

Examples


# Bucket metadata
./us3cli stat us3://bucket1

# Object metadata
./us3cli stat us3://bucket1/a.txt

du

Show storage usage for a bucket/prefix. Usage is calculated as of 00:00 of the previous day.

Syntax


us3cli du us3://<bucket>[/<prefix>] [--force] [--projectid <projectid>]

Example


./us3cli du us3://bucket1

cp

Upload / download / copy.

Syntax

Upload:


us3cli cp <local-path> us3://<bucket>/<key> [--check] [-r|--recursive] [--reduce] [--parallel <n>] [--speedlimit <rate>]
         [--storageclass <STANDARD|IA|ARCHIVE>] [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>]
         [--metadata <k=v[,k2=v2...]>] [--mimetype <type>]

Download:


us3cli cp us3://<bucket>/<key> <local-path> [-r|--recursive] [--reduce] [--parallel <n>] [--partsize <size>] [--speedlimit <rate>]
         [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>]

Copy (same region):


us3cli cp us3://<bucket>/<key> us3://<bucket>/<key> [-r|--recursive] [--reduce]
         [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>]
         [--metadata <k=v[,k2=v2...]>]

Notes

Multipart upload is used for files > 64MB; --parallel only affects multipart transfers.
On Windows, downloads avoid overwriting by adding (1), (2), etc. between the base name and extension when the target file exists.

Examples


# Upload file
./us3cli cp ./test.txt us3://bucket1/test.txt

# Upload directory with include filter
./us3cli cp -r ./dir us3://bucket1/dir --include "*.jpg"

# Download file
./us3cli cp us3://bucket1/test.txt ./test.txt

# Copy file between buckets (same region)
./us3cli cp us3://bucket1/test.txt us3://bucket2/test.txt

sync

Incrementally sync a local directory to US3.

Syntax


us3cli sync <local-dir> us3://<bucket>/<prefix> [--reduce] [--mode cache|local] [--ruler modtime|etag] [--speedlimit <rate>]
           [--retrycount <n>] [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>]
           [--parallel <n>] [--metadata <k=v[,k2=v2...]>] [--mimetype <type>] [--storageclass <class>] [--force] [--no-delete]

Notes

cache mode uses local cache to decide whether to upload; local mode compares local vs US3 and may delete extra objects in US3.

rcat

Streaming upload from stdin.

Syntax


us3cli rcat us3://<bucket>/<key> [--reduce] [--retrycount <n>] [--speedlimit <rate>] [--parallel <n>]

Example


cat test.txt | ./us3cli rcat us3://bucket1/test.txt

mkdir

Create an empty directory object in US3.

Syntax


us3cli mkdir [--parents] us3://<bucket>/<dir>[/<dir>]

cat

Streaming download to stdout.

Syntax


us3cli cat us3://<bucket>/<key> [--reduce] [--retrycount <n>] [--speedlimit <rate>] [--partsize <size>]

mv

Move objects within the same bucket.

Syntax


us3cli mv us3://<bucket>/<src> us3://<bucket>/<dst> [--force] [--reduce] [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>] [--parallel <n>]

rm

Remove objects or prefixes.

Syntax


us3cli rm us3://<bucket>/<key> [-r|--recursive] [-f|--force] [--reduce] [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>] [--qps <n>]

ls

List buckets, objects, or projects.

Syntax


us3cli ls [us3://<bucket>[/<prefix>]] [--limit <n>] [--restore] [--flat] [--mimetype] [--etag] [--project] [--projectid <projectid>]

sign

Generate a signed download URL.

Syntax


us3cli sign us3://<bucket>/<key> [--expires <seconds>]

modify

Modify object storage class / mimetype / metadata.

Syntax


us3cli modify us3://<bucket>/<key> [--storageclass <class>] [--mimetype <type>] [--metadata <k=v[,k2=v2...]>] [--replace]

restore

Restore ARCHIVE objects to a downloadable state.

Syntax


us3cli restore us3://<bucket>/<key> [-r|--recursive] [--reduce] [--qps <n>] [--exclude <glob>] [--include <glob>] [--rexclude <regex>] [--rinclude <regex>] [--parallel <n>]

etag

Calculate ETag for local files, stdin, and US3 objects.

Syntax


us3cli etag [<local-file> ...] [us3://<bucket>/<key>] [-]

create-token

Create a token.

Syntax


us3cli create-token <token-name> [--flags]

delete-token

Delete a token.

Syntax


us3cli delete-token --token-id <token-id> [--flags]

update-token

Update a token.

Syntax


us3cli update-token <token-id> [--flags]

describe-token

List/describe tokens.

Syntax


us3cli describe-token [--flags]

update

Update US3CLI to the latest version.

Syntax


us3cli update [--force]

version

Show current US3CLI version.

Syntax


us3cli version