> 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/usage/cli/assume.md).

# assume

The `assume` command is the primary command that can be used to open a Web Browser to start the SAML authentication process for role assumption

If no arguments are provided, it will prompt for available roles to assume.

The `list-roles` command will also show available Service Providers for login.

Examples:

* `saml-to assume`
  * Interactively display and allow selection of a Service Provider and roles for which to assume.
  * Then opens a browser window and begins the SAML authentication process.
* `saml-to assume arn:aws:iam::874599868815:role/iam-readonly`
  * Opens a browser window and begins the SAML authentication process.
  * No interactive prompts and requires an exact match of a provider name.

#### Suffix Matching

As an added convenience, the suffix of a role can be provided instead of the full role name, if it is distinct.

For example:

**List Roles:**

```
➜  ~ saml-to list-roles
npx: installed 1 in 3.244s
┌─────────┬───────────────────────────────────────────────┬───────────┬───────────────────────┐
│ (index) │                     role                      │ provider  │          org          │
├─────────┼───────────────────────────────────────────────┼───────────┼───────────────────────┤
│    0    │    'arn:aws:iam::874599868815:role/admin'     │ 'aws-iam' │ 'stark-international' │
│    1    │ 'arn:aws:iam::874599868815:role/iam-readonly' │ 'aws-iam' │ 'stark-international' │
└─────────┴───────────────────────────────────────────────┴───────────┴───────────────────────┘
```

**These commands are all functionally equivalent:**

```
➜  ~ saml-to assume readonly
➜  ~ saml-to assume iam-readonly
➜  ~ saml-to assume role/iam-readonly
...
➜  ~ saml-to assume arn:aws:iam::874599868815:role/iam-readonly
```

#### Headless

For some providers that have a SDK that allows for Token Generation on the command line, the `saml-to` cli is also featured to output access credentials to the command line for headless interaction.

The following providers support Headless mode:

* [AWS Federated Identity](/configuration/service-providers/aws-federated-roles.md#headless-role-assumption) (Entity ID: `https://signin.aws.amazon.com/saml`)

To see the specific interaction with Headless mode, click the links in the aforementioned list.

## Usage

```
saml-to assume [role]

Assume a role

Options:
  --help      Show help  [boolean]
  --version   Show version number  [boolean]
  --role      The role to assume  [string]
  --org       Specify an organization  [string]
  --headless  Output access credentials to the terminal  [boolean] [default: false]
  --save      Similar to headless, but saves the CLI configuration for a provider to the config file  [string]
  --provider  Specify the provider  [string]
```

## Options

### --org

In the event you're a member of multiple organizations, with providers of the same name, you can seed the command with a specific organization with this flag.

E.g. `npx saml-to login aws --org stark-international`

### --headless

No prompts, and output vary based on the provider. See [Headless](#headless) above.

## Example Output

Following these commands, a browser window would be opened to begin the SAML Authentication flow.

```
➜  ~ npx saml-to assume
npx: installed 1 in 3.035s
? Which role would you like to assume? (Use arrow keys)
  arn:aws:iam::874599868815:role/admin [aws-iam] (stark-international)
❯ arn:aws:iam::874599868815:role/iam-readonly [aws-iam] (stark-international)
Assuming arn:aws:iam::874599868815:role/iam-readonly
➜  ~ 
```

```
➜  ~ npx saml-to assume admin
npx: installed 1 in 1.592s
Assuming admin
➜  ~ 
```

```
➜  ~ npx -q saml-to assume readonly --headless
export AWS_ACCESS_KEY_ID="ASIA...AS"
export AWS_SECRET_ACCESS_KEY="X6Vo...AU"
export AWS_SESSION_TOKEN="IQoJb...=="
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.saml.to/usage/cli/assume.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.