---
title: CLI reference
description: Every rolle command.
---

The CLI and the desktop app share one workspace. A session started in one is active in the other.

```
rolle [command] [flags]
  --debug        verbose diagnostics (same as ROLLE_DEBUG=1)
  --json         machine-readable output for the list, status, start, kube, and cleanup commands
  -v, --version  print the version
```

| Exit code | Meaning |
| --- | --- |
| `0` | Success |
| `1` | Error |
| `3` | Sign-in needed. Run `rolle integration login <alias>` |
| `4` | The session or integration does not exist |

See [Agents and scripts](/agents).

## Integrations

| Command | Purpose |
| --- | --- |
| `rolle integration add aws-sso --alias A --start-url URL --region R` | Add an IAM Identity Center portal |
| `rolle integration add azure --alias A [--tenant T]` | Add an Entra ID tenant |
| `rolle integration add gcp [--alias A]` | Add your gcloud Application Default Credentials |
| `rolle integration list` | List identity sources |
| `rolle integration login <integration> [--no-browser]` | Sign in and discover roles |
| `rolle integration logout <integration>` | Sign out and stop its sessions |
| `rolle integration sync <integration>` | Rediscover accounts, subscriptions, or projects. Signs in first when needed |
| `rolle integration remove <integration>` | Remove an identity source and its sessions |

`int` is an alias for `integration`.

## Sessions

| Command | Purpose |
| --- | --- |
| `rolle session list [--all]` | List sessions. `--all` includes hidden ones |
| `rolle session hide <session>` / `unhide <session>` | Hide a session from the lists and the tray, or show it again |
| `rolle session hide --account <id>` / `unhide --account <id>` | Same for every role of an Identity Center account |
| `rolle session unhide --all` | Show every hidden session again |
| `rolle session tag <session> <tag>` / `untag <session> <tag>` | Add a session to a sidebar tag, or take it off |
| `rolle session add assume-role --name N --role-arn ARN --source S --region R [--external-id ID] [--profile P]` | Assume a role from another session |
| `rolle session add iam-user --name N --access-key-id ID --region R [--secret-access-key K] [--mfa-device M] [--profile P]` | Add an IAM user |
| `rolle session add iam-user --from-profile P [--name N] [--region R] [--mfa-device M] [--profile P2]` | Add an IAM user from the access key of a profile in `~/.aws/credentials` |
| `rolle session add gcp-impersonate --name N --project P --service-account SA [--integration I]` | Impersonate a service account |
| `rolle session profile <session> [name]` | Set the AWS profile name. Omit the name to restore `default` |
| `rolle session fix-profile <session>` | Remove the static keys in `~/.aws/credentials` that shadow the session's profile |
| `rolle session region <session> <region>` | Change the region of an AWS session |
| `rolle session remove <session>` | Remove a session |

`sess` is an alias for `session`. A `<session>` argument accepts the name or the ID.

## Tags

| Command | Purpose |
| --- | --- |
| `rolle tag list` | List tags in sidebar order |
| `rolle tag add <name> [--color #rrggbb] [--icon <name>]` | Create a tag. The icon is a [Lucide](https://lucide.dev/icons) name such as `shield` |
| `rolle tag set <name> [--name N] [--color C] [--icon I]` | Change a tag. A new name applies to every session |
| `rolle tag move <name> <index>` | Put a tag at a position in the sidebar, counting from 0 |
| `rolle tag remove <name>` | Delete a tag and take it off every session |

## Kubernetes

| Command | Purpose |
| --- | --- |
| `rolle kube list <session> [--region R]` | List the EKS, AKS, or GKE clusters a started session can reach |
| `rolle kube add <session> [cluster ...] [--all] [--region R] [--kubeconfig PATH] [--context NAME] [--use]` | Write a kubeconfig context per cluster that authenticates through the session |
| `rolle kube attach <session> <context> [--kubeconfig PATH]` | Make an existing context authenticate through the session |
| `rolle kube token <session>` | Print an `ExecCredential` for kubectl. The AKS and GKE contexts from `kube add` run this |

[Kubernetes](/integrations/kubernetes) covers authentication per cloud.

## Credentials

| Command | Purpose |
| --- | --- |
| `rolle start <session> [--mfa-code C]` | Start a session |
| `rolle stop <session>` | Stop a session |
| `rolle status` | Show active sessions |
| `rolle cleanup [profile ...] [--all]` | List the sections of `~/.aws/credentials` that hold static keys, or remove their keys |
| `rolle env <session> [--powershell]` | Print credentials as shell exports |
| `rolle token <session>` | Print the bearer token of an Azure or Google Cloud session |
| `rolle shell <session>` | Open a terminal window with the credentials ready |
| `rolle console <session> [--print]` | Open the cloud console |
| `rolle reset [--yes]` | Remove every session, integration, secret, and cached credential |
| `rolle completion <shell>` | Shell completion script |