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