> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/aws-cli

Install and configure the AWS command-line interface (awscli) version 2.
(To use AWS CLI v1 view version 1.4.1 of this orb)

Supports Linux x86_64, MacOS, Arm64 V8 and Windows with bash.exe


## Commands

### install

Install the AWS CLI via Pip if not already installed.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `binary_dir` | string | /usr/local/bin | The main aws program in the install directory is symbolically linked to the file aws in the specified path. Defaults to /usr/local/bin
 |
| `disable_aws_pager` | boolean | true | Set to false to skip forceful disabling of all AWS CLI output paging.
 |
| `install_dir` | string | /usr/local/aws-cli | Specify the installation directory of AWS CLI. Defaults to /usr/local/aws-cli
 |
| `override_installed` | boolean | false | By default, if the AWS CLI is detected on the system, the install will be skipped.
Enable this to override the installed version and install your specified version.
 |
| `use_brew` | boolean | false | Set to true if you want to use the Homebrew CLI to install the awscli. Only compatible with the macOS executor. Defaults to false.
When using brew, only the brew version is available.
 |
| `version` | string | latest | Select a specific version of the AWS v2 CLI. By default the latest version will be used.
This value is ignored on Alpine, and the default version on the repositories is installed.
 |
| `when` | enum | on_success | Allows script to run on a specific condition of a workflow.
The default is 'on_success', means the script will run only if all previous steps were successful
'on_fail' means the script will run if any previous step fails
'always' means it will run regardless of the success or failure of previous steps in the workflow
 |

### role_arn_setup

Create a new profile with role arn and source profile


| Parameter | Type | Default | Description |
|---|---|---|---|
| `profile_name` | string |  | Name of new profile associated with role arn. |
| `role_arn` | string |  | Role ARN that the profile should take. |
| `source_profile` | string | default | Source profile containing credentials to assume the role with role_arn. |
| `when` | enum | on_success | Allows script to run on a specific condition of a workflow.
The default is 'on_success', means the script will run only if all previous steps were successful
'on_fail' means the script will run if any previous step fails
'always' means it will run regardless of the success or failure of previous steps in the workflow
 |

### setup

Installs aws-cli and then configure and store AWS credentials in
~/.aws/credentials and ~/.aws/config.
If role_session_name and role_arn are provided, it will attempt to use OIDC auth.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `aws_access_key_id` | string | $AWS_ACCESS_KEY_ID | AWS access key. By default this will be set to the $AWS_ACCESS_KEY_ID.
If you don't have these variable in your context, update the value.
 |
| `aws_secret_access_key` | string | $AWS_SECRET_ACCESS_KEY | AWS secret key. By default this will be set to the $AWS_SECRET_ACCESS_KEY.
If you don't have these variable in your context, update the value.
 |
| `binary_dir` | string | /usr/local/bin | The main aws program in the install directory is symbolically linked to the file aws in the specified path. Defaults to /usr/local/bin
 |
| `configure_default_region` | boolean | true | Some AWS actions don't require a region; set this to false if you do not want to store a default region in ~/.aws/config
Any AWS CLI command will default to this region if none is specified with the --region CLI parameter.
 |
| `configure_profile_region` | boolean | true | Boolean whether to configure the region for the custom (non-default) profile. The specified region will be used for AWS CLI
commands executed under that specific profile using the --profile CLI parameter.
 |
| `disable_aws_install` | boolean | false | Set to true if you want to disable the AWS CLI install step. Default to false.
 |
| `disable_aws_pager` | boolean | true | Set to false to skip forceful disabling of all AWS CLI output paging.
 |
| `install_dir` | string | /usr/local/aws-cli | Specify the installation directory of AWS CLI. Defaults to /usr/local/aws-cli
 |
| `override_installed` | boolean | false | By default, if the AWS CLI is detected on the system, the install will be skipped.
Enable this to override the installed version and install your specified version.
 |
| `profile_name` | string | default | Profile name to be configured. |
| `region` | string | ${AWS_DEFAULT_REGION} | AWS region to operate in
(defaults to env var of ${AWS_DEFAULT_REGION})
 |
| `role_arn` | string |  | The Amazon Resource Name (ARN) of the role that the caller is assuming.
Role ARN must be configured for web identity.
 |
| `role_session_name` | string | ${CIRCLE_JOB} | An identifier for the assumed role session |
| `session_duration` | string | 3600 | The duration of the session in seconds |
| `set_aws_env_vars` | boolean | true | Write AWS keys generated from OIDC to a temporary file.
Set to false if generating keys for multiple profiles.
By default, the keys are written to $BASH_ENV.
 |
| `use_brew` | boolean | false | Set to true if you want to use brew to install the awscli. Only compatible with MacOs executor. Default to false.
When using brew, only the brew version is available.
 |
| `version` | string | latest | Select a specific version of the AWS v2 CLI. By default the latest version will be used. |
| `when` | enum | on_success | Allows script to run on a specific condition of a workflow.
The default is 'on_success', means the script will run only if all previous steps were successful
'on_fail' means the script will run if any previous step fails
'always' means it will run regardless of the success or failure of previous steps in the workflow
 |

## Executors

### default

A base Ubuntu Docker image built to run on CircleCI


| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | current | Select your version or any of the available tags here: https://hub.docker.com/r/cimg/base.
 |

## Examples

### configure_role_arn

Configure a new profile to assume a role defined by a role_arn. Must first authenticate with
OIDC or static AWS Keys stored as environment variables in CircleCI.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1
jobs:
  configure_role_arn:
    executor: aws-cli/default
    steps:
      - checkout
      - aws-cli/setup:
          profile_name: default
      - aws-cli/role_arn_setup:
          profile_name: new-profile
          role_arn: arn:aws:iam::123456789012:role/example-role
          source_profile: default
      - run: >-
          aws sts assume-role --role_arn
          "arn:aws:iam::123456789012:role/example-role" --role_session_name
          AWSCLI-Session
workflows:
  aws-cli:
    jobs:
      - configure_role_arn
```

### install_aws_cli

Easily install and configure the AWS CLI automatically in your jobs or commands.

```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1
jobs:
  aws-cli-example:
    executor: aws-cli/default
    steps:
      - checkout
      - aws-cli/setup:
          profile_name: example
      - run: echo "Run your code here"
workflows:
  aws-cli:
    jobs:
      - aws-cli-example:
          context: aws
```

### install_aws_cli_with_web_identity

Setup the AWS CLI and configure with Web Identity.
Assume roles on AWS without storing keys on CircleCI and utilize short-term credentials instead.
For more information, see the CircleCI OIDC docs: https://circleci.com/docs/2.0/openid-connect-tokens


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1
jobs:
  aws-cli-example:
    executor: aws-cli/default
    steps:
      - checkout
      - aws-cli/setup:
          profile_name: WEB IDENTITY PROFILE
          role_arn: arn:aws:iam::123456789012:role/WEB-IDENTITY-ROLE
          role_session_name: example-session
      - run: echo "Run your code here"
workflows:
  aws-cli:
    jobs:
      - aws-cli-example:
          context: aws
```