# switch-profile

> Switch between AWS accounts in one keystroke, with SSO done properly. I built it because nothing else did the job, and I use it many times a day.

- Verdict: My default
- Vendor: Cloudless Labs (open source, by Nicolas Dao)
- Layer: [Accounts, identity and cost](https://cloudlesslabs.com/stack/layers/accounts/index.md). Job: AWS profile and SSO switcher
- Last reviewed: 21 October 2026, by Nicolas Dao (Cloudless Labs, Sydney)
- Web page: https://cloudlesslabs.com/stack/switch-profile/. The whole stack in one file: https://cloudlesslabs.com/stack/brief.md

My own tool, so read this with the bias on the table. I built switch-profile because I never found a tool that let me switch between AWS profiles quickly, set them up with SSO without pain, and see at a glance where I was. I run it many times a day across every client account I work in.

Type `sp` and you get a searchable list of your accounts, most used first. Type `sp acme prod` and you're in, as long as exactly one profile matches. Every switch checks who you really are with `aws sts get-caller-identity`, production accounts get a red PROD badge, and stray environment variables that would silently override your choice are flagged. One command, `add --from-sso`, creates a profile for every account and role in an Identity Center portal, and running it again re-syncs and prunes the ones that are gone (never the ones you wrote by hand).

What I care about most is that it doesn't invent anything. Logins go through the official AWS CLI, credentials refresh through the CLI's own `[sso-session]`, and the tool stores no tokens and sends no telemetry. When you switch, it writes the profile's settings into `~/.aws/config` and nothing else, so Terraform, Pulumi, the SDKs and your IDE work without a wrapper process.

It's also built for the way I work now, with agents. A box with no browser gets a device code automatically, copied to my laptop's clipboard with a warning to approve only that exact code. An agent gets JSON, no prompts and a clear contract: exit code 2 means "a human has to log in", so it can ask me instead of failing in a loop.

Where something else wins: [aws-vault](https://github.com/ByteNess/aws-vault) if you must keep long-lived keys (it encrypts them; I'd rather not have them at all), [Granted](https://github.com/fwdcloudsec/granted) for browser console tabs per account, and [aws-sso-cli](https://github.com/synfinatic/aws-sso-cli) if you want SSO tokens encrypted at rest. For switching profiles in a terminal with SSO, nothing I've tried comes close.

## Use it when

- You work across many AWS accounts (clients, environments) and switch between them all day.
- Your access is IAM Identity Center (SSO): import every account and role of a portal in one command, and re-sync it when access changes.
- You log in from an SSH box with no browser: it switches to a device code on its own, puts the code on your laptop's clipboard and shows a QR code.
- AI agents and scripts run AWS commands for you: JSON output, no prompts without a terminal, and exit code 2 when a human has to log in.

## Don't use it when

- You must keep long-lived access keys: aws-vault stores them encrypted in the OS keychain. switch-profile writes key profiles to the plain ~/.aws/credentials, and warns before it does.
- What you need is browser console tabs per account, or access requests with a justification: Granted does those.
- You can't add a single dependency: the plain AWS CLI (aws configure sso, then AWS_PROFILE) does the minimum.

## Pricing

Free and open source (BSD-3-Clause). npx switch-profile, or npm install -g switch-profile.

## Gotchas, with fixes

- **Gotcha:** Switching rewrites [default] in ~/.aws/config, so it changes the account for every terminal and every running process (Terraform, IDE plugins) on the machine.
  **Fix:** Use the sp shortcut, which sets AWS_PROFILE in the current terminal only. In scripts and agents, prefix every command with the profile (AWS_PROFILE=acme-prod aws …) and never rely on [default].
- **Gotcha:** Fuzzy matching is ambiguous in scripts: sp prod matches every client's prod.
  **Fix:** Use switch-profile use <exact-name> in scripts. Ambiguous input exits with code 3 instead of guessing.
- **Gotcha:** "Invalid start url provided" or invalid_grant at login usually means the portal's SSO region is wrong, not the URL.
  **Fix:** Run sp portals: it detects the right region and fixes it.
- **Gotcha:** Accounts you reach through the console's account access manager don't work with aws sso login.
  **Fix:** Add them as console sign-in profiles (aws login), which needs AWS CLI 2.32 or later.
- **Gotcha:** The device code doesn't reach the clipboard inside tmux.
  **Fix:** Set set -g set-clipboard on in tmux, or press q and scan the QR code.

## Instead, consider

- [AWS Organizations + IAM Identity Center](https://cloudlesslabs.com/stack/aws-organizations-identity-center/index.md): The other half: Identity Center defines who can reach which account; switch-profile gets you into them from the terminal.

## Sources

- [switch-profile on GitHub (README)](https://github.com/nicolasdao/switch-profile)
- [switch-profile changelog](https://github.com/nicolasdao/switch-profile/blob/master/CHANGELOG.md)
- [AWS CLI: configuring IAM Identity Center authentication](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html)
- [aws-vault (maintained fork)](https://github.com/ByteNess/aws-vault)
- [Granted](https://github.com/fwdcloudsec/granted)
- [aws-sso-cli](https://github.com/synfinatic/aws-sso-cli)

## Related

- [Accounts, identity and cost](https://cloudlesslabs.com/stack/layers/accounts/index.md): every tool in this layer, with its verdict
- [The whole stack in one file](https://cloudlesslabs.com/stack/brief.md): every use case and tool, for questions that span many
- [Map of every Markdown file on cloudlesslabs.com, with what each one answers](https://ask.cloudlesslabs.com)