# Use AWS CLI

The AWS commandline interface (CLI) is a unified tool to manage your AWS
services, including AWS S3. Here we will show you how to configure
and use AWS CLI to manage your SOS buckets.

## Installation

You can install AWS CLI using your package manager or by downloading the latest
version from the
[AWS website](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).

## Create an IAM key

You need an IAM api-key with a policy that allows the management of SOS buckets.
A simple policy that allows all operations on all buckets is:

```json
{
  "default-service-strategy": "deny",
  "services": {
    "sos": {
      "type": "allow"
    }
  }
}
```

You find more information about key management and IAM policies in the
[IAM documentation](https://community.exoscale.com/product/security/iam/how-to/key-mgmt/).

## Configure your AWS CLI

You can configure your AWS CLI interactively using the `aws configure`
command or with a script. Here is an example of a script that you can use to
configure a new `exoscale` profile for your AWS CLI:

```bash
export AWS_PROFILE=exoscale
S3_REGION="ch-gva-2"

# Assuming you have stored your Exoscale api-key and api-secret in `pass` password store.
aws configure set aws_access_key_id "$(pass exoscale/api_key)"
aws configure set aws_secret_access_key -- "$(pass exoscale/api_secret)" # Note the double hyphen!
aws configure set region "${S3_REGION}"
aws configure set endpoint_url "https://sos-${S3_REGION}.exo.io"
```

The double hyphen is required to prevent the AWS CLI from interpreting a secret
that starts with a hyphen as a flag. Exoscale's secrets sometimes start with a
hyphen.

## Test your configuration

Now you are ready to use your SOS bucket with the AWS CLI. The following
commands will create a bucket, list buckets, and delete the bucket using the
`exoscale` profile.

```bash
export AWS_PROFILE=exoscale
BUCKET="aws-cli-bucket-$(uuidgen)" # Must be unique as per S3 specs.

aws s3 mb "s3://${BUCKET}"
aws s3 ls
aws s3 rb "s3://${BUCKET}"
aws s3 ls
```

## Advanced usage

The command `aws s3` covers only basic operations. For advanced usage, you
can use the `aws s3api` command. For example, you can list the oldest five 
versions of a bucket's object(s) using the following command:

```bash
export AWS_PROFILE=exoscale
export AWS_REGION=at-vie-1
export AWS_ENDPOINT_URL="https://sos-${AWS_REGION}.exo.io"
BUCKET="your-sos-bucket"
TMP=$(mktemp -t s3-delete-XXX)

# Prefix, query and output are optional.
aws s3api list-object-versions \
    --bucket "$BUCKET" \
    --prefix "your-prefix/your-object" \
    --query '{Objects:Versions | sort_by(@, &LastModified)[:5].{Key:Key,VersionId:VersionId}}' \
    --output json | tee "$TMP"
```
The command above will create a temporary file containing a correctly formatted 
list of versions that you can use to delete them:

```bash
aws s3api delete-objects \
    --bucket "$BUCKET" \
    --delete "file://$TMP" \
    --debug # To see what's going on.
```

A list of all available `aws s3/s3api` commands can be found at:

[https://docs.aws.amazon.com/cli/latest/reference/s3](https://docs.aws.amazon.com/cli/latest/reference/s3)<br>
[https://docs.aws.amazon.com/cli/latest/reference/s3api](https://docs.aws.amazon.com/cli/latest/reference/s3api)