Switching between different AWS profiles is a common task for those managing multiple AWS accounts.
Whether you’re a developer working on various projects or an administrator overseeing different environments, knowing how to switch profiles using the AWS CLI can save you time and streamline your workflow.
To temporarily switch profiles using the AWS CLI, you have to add the argument
--profile <my-profile-name> to your AWS CLI command.
This guide will walk you through the process, step by step.
Table of Contents
How to configure an AWS CLI Profile
Before you can switch between profiles using the AWS CLI, you need to have them configured. There’s two ways you can configure an AWS profile, one is via storing IAM User credentials. The other method is configuring an AWS SSO User.
1. Using IAM User Credentials
Here’s how to create a new profile using IAM User credentials:
Create a New Profile: Use the following command to create a new profile:
aws configure --profile <my-profile-name>
Follow the prompts to enter your AWS Access Key ID, Secret Access Key, default region, and output format.
The new user credentials will be stored at
~/.aws/credentials. This method is not the safest way to store user credentials since the credentials are stored as plaintext and can be used for a long term.
We recommend you to use the second method which is using an AWS SSO user to store you AWS profile on your system.
2. Using AWS SSO user
If you’re using AWS Single Sign-On (SSO), you can configure a profile as follows:
Run the following command to start the configuration process:
aws configure sso --profile my-sso-profile
Next, Enter your SSO Details. You’ll be prompted to enter your SSO start URL, the region where your SSO is configured, and the account and role you want to assume.
The new SSO profile will be stored at
This is a lot safer than the previous method since it will only store the SSO account details as you can see in the example config below:
[profile example-account-sso] sso_start_url=https://d-534987gbn.awsapps.com/start sso_region=eu-west-1 sso_account_id=123456789012 sso_role_name=AdministratorAccess region=eu-west-1
These account details are then used to authenticate with AWS by opening a browser window, asking you to authenticate with your SSO provider. Once authenticated, the CLI will store the temporary credentials and refresh them as needed.
How to list your configured AWS Profiles
To see a list of all the configured profiles, you can use the following command:
aws configure list-profiles
This will display all the profiles that you have configured on your system.
➜ aws configure list-profiles default example-account-sso example-account-2-sso example-account-3-sso
How to switch profiles using the AWS CLI
Now that you have your AWS profiles configured in the CLI, switching between profiles is pretty easy.
You can specify the profile directly in your AWS CLI command by using the
--profile option when you run a generic AWS CLI command.
For instance if you would like to list all the S3 buckets in your AWS account:
aws s3 ls --profile <my-profile-name>
Alternative option to switching profiles
I’ve been using an open-source tool called Granted CLI, developed by Common-Fate that makes it easier manage AWS profiles.
In this blog post I explain in more detail how you can leverage this tool to assume IAM Roles and IAM users sessions easily via a single command.
Switching profiles using the AWS CLI is a vital skill for anyone working with multiple AWS accounts. By understanding how to configure, list, and switch profiles, you can efficiently manage your various environments.
Even though I’ve outlined two methods of configuring AWS profiles, It’s recommended to stick with AWS SSO when you want to manage and control AWS account from your local system.
Because if your system gets compromised, the bad actor won’t have access to your environments since AWS SSO makes use of temporary credentials compared to IAM users that use long term credentials.
So if you’d want to easily switch AWS profiles in your terminal then make sure to use the
--profile in your AWS CLI command to execute the command on the appropriate AWS account.