> For the complete documentation index, see [llms.txt](https://docs.saml.to/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saml.to/configuration/service-providers/aws-federated-roles/assuming-roles/aws-cli.md).

# AWS CLI

The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) has various methods for using an AWS Token on a system, wether it be in on a Developer System, or CI/CD (such as GitHub Actions).

## Using Environment Variables

<details>

<summary>In an Interactive Terminal (e.g. Developer Laptop)</summary>

Add the `--headless` flag to the `saml-to assume` command in a subshell `$(...)`

```
$(saml-to assume the-role-name --headless)
aws sts get-caller-identity # (optional, shows the identity that is now assumed)
aws ec2 describe-instances # (or whatever AWS CLI command desired)
```

</details>

<details>

<summary>In GitHub Actions</summary>

In the Workflow YAML, use provide the Repository Secret (automatically generated using `${{ secrets.GITHUB_TOKEN }}` and the [Assume AWS Role Action](https://github.com/marketplace/actions/saml-to-assume-aws-role)

```
steps:
  - uses: saml-to/assume-aws-role-action@v1
    with:
      role: arn:aws:iam::123456789012:role/admin
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  - run: aws sts get-caller-identity # (optional, shows the identity that is now assumed)
  - run: aws ec2 describe-instances # (or whatever AWS CLI command desired)
```

</details>

## Using Profiles

<details>

<summary>In an Interactive Terminal (e.g. Developer Laptop)</summary>

Add the `--save` flag to the `saml-to assume` command

```
saml-to assume the-role-name --save
aws sts get-caller-identity --profile the-role-name
aws ec2 describe-instances --profile the-role-name
```

</details>

<details>

<summary>In GitHub Actions</summary>

Add the `profile:` option to the [Assume AWS Role Action](https://github.com/marketplace/actions/saml-to-assume-aws-role)

```
steps:
  - uses: saml-to/assume-aws-role-action@v1
    with:
      role: arn:aws:iam::123456789012:role/admin
      profile: the-profile-name
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  - run: aws sts get-caller-identity # (optional, shows the identity that is now assumed)
  - run: aws ec2 describe-instances # (or whatever AWS CLI command desired)
```

</details>

### Named Profiles

Named Profiles are useful if you need to access multiple AWS accounts or Roles in the same session

<details>

<summary>In an Interactive Terminal (e.g. Developer Laptop)</summary>

```
saml-to assume the-role-name --save role1
saml-to assume another-role-name --save role2
aws sts get-caller-identity --profile role1
aws sts get-caller-identity --profile role2
aws ec2 describe-instances --profile role1
aws ec2 describe-instances --profile role2
```

</details>

<details>

<summary>In GitHub Actions</summary>

```
steps:
  - uses: saml-to/assume-aws-role-action@v1
    with:
      role: arn:aws:iam::123456789012:role/some-role
      profile: role1
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  - uses: saml-to/assume-aws-role-action@v1
    with:
      role: arn:aws:iam::123456789012:role/another-role
      profile: role2
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  - run: aws sts get-caller-identity --profile role1
  - run: aws sts get-caller-identity --profile role2
```

</details>