# Assuming Roles

## With the CLI

First, [install the `saml-to` CLI](https://github.com/saml-to/cli).

### Listing Roles

To know which roles are available to assume, use the `list-roles` subcommand.

```
saml-to list-roles
```

### Assuming Roles

### Using the Terminal to open a Browser Window

To interactively prompt for a role to assume, use the following command:

```
saml-to assume
```

Or, to assume a specific role, first [List Roles](#listing-roles), and provide the Role Name:

```
saml-to assume arn:aws:iam::123456789012:role/administrator
```

{% hint style="success" %}
Protip: You can use substring matching for role names.

\
If the Role ARN outputted from `list-roles` is `arn:aws:iam::123456789012:role/administrator`, then you can shorten it with **any unique substring** of that Role ARN.

\
For example:\
  `saml-to assume arn:aws:iam::123456789012:role/administrator`

May be shortened to:\
  `saml-to assume administrator`
{% endhint %}

### Using Environment Variables

If you add the `--headless` flag to a `saml-to assume` command, the appropriate environment variables will be added to the terminal environment:

```
$(saml-to assume administrator --headless)
```

Then, you may run AWS CLI commands, or run any process that uses the Environment Variables, such as the AWS SDK:

```
aws sts get-caller-identity
```

## In the Browser

Go to [SAML.to Apps](https://saml.to/apps) and AWS roles can be assumed by clicking on the desired "Assume" button for a listed role.