# Quick Start

- [Configuration management](#configuration-management)
- [Create a bucket](#create-a-bucket)
- [Upload a file or directory](#upload-a-file-or-directory)
- [Download a file or directory](#download-a-file-or-directory)
- [Copy a file or directory](#copy-a-file-or-directory)
- [Delete a file or directory](#delete-a-file-or-directory)
- [View object metadata](#view-object-metadata)
- [Modify object metadata](#modify-object-metadata)

## Configuration management

US3CLI supports both **saved profiles** and **temporary configuration**. A profile contains `accesskey`, `secretkey`, `endpoint`, and optional settings such as HTTPS, proxy, and credential encryption.

### Create or manage saved profiles

Command format:

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

Interactive example (sample output):

```
$ ./us3cli config
Please enter the language (ZH/EN), default is ZH: EN
Enter profile name: config1
Create new profile: [ config1 ]
Enable credential encryption (y or n)? n
Enter API/Token AccessKey: xxxxxxxxxxxxxxxxxxxxxx
Enter API/Token SecretKey: xxxxxxxxxxxxxxxxxxxxxx
Select region number: 0
Select network (public/intranet): 0
Endpoint (press Enter to accept default): cn-bj.ufileos.com
Enable HTTPS (y or n)? n
Enable proxy (y or n)? n
Profile [ config1 ] updated
Set as default profile (y or n)?
```

Common management examples:

```
# List profiles
./us3cli config --ls

# Switch default profile
./us3cli config --su config1

# Delete a profile
./us3cli config --rm config1

# View profile content
./us3cli config --cat config1
```

### Temporary configuration

Temporary config can be provided via profile name, config file path, or inline fields:

```
# Use a saved profile
./us3cli ls us3://bucket1 --config config2

# Use a config file path
./us3cli ls us3://bucket1 --config ~/myconfig.yaml

# Inline config fields (only effective for this command)
./us3cli ls us3://bucket1 --accesskey "xxxxxx" --secretkey "xxxxxx" --endpoint "xxxxxx"
```

## Create a bucket

```
# Interactive
us3cli mb us3://<bucketname>

# Non-interactive
us3cli mb us3://<bucketname> --projectid <projectid> --region <region> --acl <private|public>
```

Example:

```
./us3cli mb us3://buckettest --projectid org-test --region cn-bj --acl public
```

## Upload a file or directory

```
# Upload a file
us3cli cp <local-file> us3://<bucket>/<key>

# Upload a directory
us3cli cp -r <local-dir> us3://<bucket>/<prefix>

# Incremental upload (sync)
us3cli sync <local-dir> us3://<bucket>/<prefix>

# Streaming upload
cat test.txt | us3cli rcat us3://<bucket>/<key>
```

## Download a file or directory

```
# Download a file
us3cli cp us3://<bucket>/<key> <local-file>

# Download a directory
us3cli cp -r us3://<bucket>/<prefix> <local-dir>

# Streaming download
us3cli cat us3://<bucket>/<key> > out.file
```

## Copy a file or directory

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

# Copy a directory
us3cli cp -r us3://bucket1/dir us3://bucket2/dir
```

## Delete a file or directory

```
# Delete a file
us3cli rm us3://<bucket>/<key>

# Delete a directory (prefix)
us3cli rm -r us3://<bucket>/<prefix>

# Force delete
us3cli rm -f us3://<bucket>/<key>
us3cli rm -r -f us3://<bucket>/<prefix>
```

## View object metadata

```
us3cli stat us3://<bucket>/<key>
```

## Modify object metadata

```
# Set mimetype
us3cli modify us3://<bucket>/<key> --mimetype <type>

# Set metadata
us3cli modify us3://<bucket>/<key> --metadata key1=value1,key2=value2

# Replace (clear old metadata first)
us3cli modify us3://<bucket>/<key> --metadata "key1=value1" --replace

# Change storage class
us3cli modify us3://<bucket>/<key> --storageclass STANDARD|IA|ARCHIVE
```