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


---

# 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.saml.to/configuration/service-providers/aws-federated-roles/assuming-roles.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.