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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coldstack.io/tools/supported-tools/aws-cli-console-client.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.