# AWS CLI (/tools/s3-gateway/quickstarts/aws-cli)

## Before you start

* [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
* Your access key ID, API key and bucket name from [console.shelby.xyz](https://console.shelby.xyz)

Export your credentials and bucket name from the
[console](https://console.shelby.xyz) so the commands below can use them:

```bash
export SHELBY_ACCESS_KEY_ID="<your access key ID, SHLB…>"
export SHELBY_SECRET_ACCESS_KEY="<your API key>"
export SHELBY_BUCKET="<your bucket name>"
```

<Steps>
  <Step>
    ### Create a `shelby` profile

    ```bash
    aws configure set aws_access_key_id "$SHELBY_ACCESS_KEY_ID" --profile shelby
    aws configure set aws_secret_access_key "$SHELBY_SECRET_ACCESS_KEY" --profile shelby
    aws configure set region default --profile shelby
    aws configure set endpoint_url https://s3.beta.shelby.xyz --profile shelby
    aws configure set s3.addressing_style path --profile shelby
    aws configure set request_checksum_calculation when_required --profile shelby
    ```

    The last setting stops the CLI from sending uploads in `aws-chunked` framing, which it
    does by default (CLI 2.23 and later) and Shelby doesn't accept yet. Without it, uploads
    fail with `501 NotImplemented`.
  </Step>

  <Step>
    ### Upload a file

    ```bash
    export AWS_PROFILE=shelby
    echo "Hello, Shelby" > hello.txt
    aws s3 cp hello.txt "s3://$SHELBY_BUCKET/examples/hello.txt"
    ```
  </Step>

  <Step>
    ### List and download it

    ```bash
    aws s3 ls "s3://$SHELBY_BUCKET/examples/"
    aws s3 cp "s3://$SHELBY_BUCKET/examples/hello.txt" hello-copy.txt
    ```

    A new object can take a few seconds to appear in listings. If the listing is empty, run it
    again.
  </Step>

  <Step>
    ### Check the round trip

    ```bash
    shasum -a 256 hello.txt hello-copy.txt
    ```

    Both lines should show the same hash.
  </Step>

  <Step>
    ### Clean up

    ```bash
    aws s3 rm "s3://$SHELBY_BUCKET/examples/hello.txt"
    ```
  </Step>
</Steps>

## Sync a directory

```bash
aws s3 sync ./data "s3://$SHELBY_BUCKET/data/"
```

Large files are uploaded in parts automatically.

## What's different with the AWS CLI

* **`aws s3 mv`, and `aws s3 cp` from one Shelby key to another, fail.** Both need
  server-side copy. Download the object and upload it again instead.
* **`aws s3 ls`, `sync` and `rm --recursive` can miss objects written in the last few
  seconds.** They work from listings, and a new object takes a few seconds to appear in
  one. A `sync` straight after an upload can upload the same file again.
* **Files over about 23 GiB need a larger part size.** Shelby allows 3,000 parts per
  upload, and the CLI's default part size is 8 MiB. Raise it with
  `aws configure set s3.multipart_chunksize 64MB --profile shelby`.

[Compatibility matrix](/tools/s3-gateway/compatibility) ·
[Troubleshooting](/tools/s3-gateway/troubleshooting)