# 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](https://docs.saml.to/configuration/service-providers/aws-federated-roles#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: 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/usage/cli/assume.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.