# AWS CLI Console client

[AWS CLI](https://aws.amazon.com/ru/cli/) — is a command line interface for working with AWS services. For the [general order of calling commands](https://docs.aws.amazon.com/cli/latest/reference/), see the official Amazon documentation.

To work with ColdStack using AWS CLI, you can use the following sets of commands:

* [s3api](https://docs.aws.amazon.com/cli/latest/reference/s3api/index.html) — commands corresponding to operations in the REST API. Please check the [list of supported operations](https://docs.coldstack.io/http-api-compatible-with-amazon-s3/api-reference#operations-list) before use.
* [s3](https://docs.aws.amazon.com/cli/latest/reference/s3/index.html) — additional commands that simplify work with a large number of objects.

### Preparation for work

Current status of the system is private alpha testing. To get an access key, you need to contact the admin in [our telegram channel](https://t.me/coldstackio) to get an access key. Please note that you cannot upload more than 10Tb during this test.

### Installation <a href="#installation" id="installation"></a>

To install the AWS CLI, follow the [instructions](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) on the manufacturer's website.

### Setting up <a href="#setup" id="setup"></a>

Use the `aws configure` command to configure the AWS CLI. The command will ask for values for the following parameters:

1. `AWS Access Key ID` — enter the key id that you received from our admin.
2. `AWS Secret Access Key` — enter the secret key that you received from our admin.
3. `Default region name` — enter value `us-east-1`.

   **Note**\
   To work with ColdStack, always specify the region `us-east-1`. Other region values may result in an authorization error.
4. `Default output format` - leave unchanged.
5. Leave the rest of the parameters unchanged.

#### Config files

As a result of its work, the `aws configure` command will save the settings in files:

* Static key in `.aws/credentials` in the following format:

  ```
  [default]
              aws_access_key_id = id
              aws_secret_access_key = secretKey
  ```
* Default region in `.aws/config` in the following format:

  ```
  [default]
              region=us-east-1
  ```

### Notes <a href="#specifics" id="specifics"></a>

When using AWS CLI to work with ColdStack, consider the following features of this tool:

* AWS CLI treats Object Storage as a hierarchical file system and object keys are in the form of a file path.
* When running the aws command to work with ColdStack, the `--endpoint` parameter is required, and the value should be `https://s3.coldstack.io` since by default the client is configured to work with Amazon servers.
* When working in macOS, in some cases it is required to launch the following:

  ```
  export PYTHONPATH=/Library/Python/2.7/site-packages; aws --endpoint-url=https://s3.coldstack.io s3 ls
  ```

### Examples <a href="#aws-cli-examples" id="aws-cli-examples"></a>

#### Create a bucket and list them

Lets check what buckets do you own:

```bash
aws --endpoint=https://s3.coldstack.io s3 ls
```

If you are a new user and have not created any bucket yet, then this command will not show any buckets. You have to create a bucket for yourself. Lets do it, just replace `my-new-bucket`  with your desired name:

```bash
aws --endpoint=https://s3.coldstack.io s3 mb s3://my-new-bucket
```

Now you created a bucket, lets list them one more time:

```bash
aws --endpoint=https://s3.coldstack.io s3 ls
```

At this moment you should see at least one bucket, that you just created:

```
2021-08-18 11:31:56 my-new-bucket
```

#### Upload objects <a href="#uploading-objects" id="uploading-objects"></a>

You can load objects in different ways, for example:

* Load all objects from local directory:

  ```
  aws --endpoint=https://s3.coldstack.io \
      s3 cp --recursive local_files/ s3://my-new-bucket/path_style_prefix/
  ```
* Load objects described in the `--include` filter and skip objects described in the `--exclude` filter

  ```
  aws --endpoint=https://s3.coldstack.io \
      s3 cp --recursive --exclude "*" --include "*.log" \
      local_files/ s3://my-new-bucket/path_style_prefix/
  ```
* Load objects one at a time by running a command of the following type for each object:

  ```
  aws --endpoint=https://s3.coldstack.io \
      s3 cp testfile.txt s3://my-new-bucket/path_style_prefix/textfile.txt
  ```

#### Get the list of objects <a href="#getting-objects-list" id="getting-objects-list"></a>

```
aws --endpoint=https://s3.coldstack.io \
    s3 ls --recursive s3://my-new-bucket
```

#### Get an object <a href="#retrieving-objects" id="retrieving-objects"></a>

```
aws --endpoint=https://s3.coldstack.io \
    s3 cp s3://my-new-bucket/textfile.txt textfile.txt
```