How to Switch AWS CLI Profiles: 3 Methods + Troubleshooting

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.

In this guide, you'll learn three methods to switch AWS CLI profiles, how to verify which profile is currently active, platform-specific commands for Windows and Linux/macOS, and how to troubleshoot common profile issues.

How to Configure an AWS CLI Profile

Before you can switch between profiles using the AWS CLI, you need to have them configured. The AWS CLI stores configuration in two separate files: ~/.aws/credentials for sensitive credential information and ~/.aws/config for less sensitive settings like region and output format.

There are two ways you can configure an AWS profile: storing IAM User credentials or 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.

Security Warning: The credentials will be stored as plaintext in ~/.aws/credentials. Long-term IAM user credentials pose a security risk because they don't expire automatically and can be compromised if your system is breached. For better AWS account security best practices, I recommend using AWS SSO instead.

2. Using AWS SSO User

If you're using AWS Single Sign-On (SSO), you can configure a profile with temporary credentials that auto-refresh:

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 modern way to configure SSO is using SSO sessions. This creates both an sso-session section and a profile in ~/.aws/config:

[profile dev-readonly]
sso_session = company-sso
sso_account_id = 111111111111
sso_role_name = ReadOnly
region = us-west-2

[sso-session company-sso]
sso_region = us-east-1
sso_start_url = https://company.awsapps.com/start
sso_registration_scopes = sso:account:access

The real power of SSO sessions is that a single SSO login can serve multiple profiles. You authenticate once and access all accounts that share the same sso-session:

[profile dev-readonly]
sso_session = company-sso
sso_account_id = 111111111111
sso_role_name = ReadOnly

[profile prod-admin]
sso_session = company-sso
sso_account_id = 222222222222
sso_role_name = AdminAccess

[sso-session company-sso]
sso_region = us-east-1
sso_start_url = https://company.awsapps.com/start

To authenticate, run:

aws sso login --sso-session company-sso

This is significantly safer than IAM user credentials because SSO provides temporary credentials that auto-refresh. If your system gets compromised, attackers only have access until the temporary credentials expire.

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
dev-readonly
prod-admin
staging

To view the detailed configuration for a specific profile, including where each setting comes from:

aws configure list --profile dev-readonly

This shows the configuration values and their sources:

$ aws configure list --profile dev-readonly
      Name                    Value             Type    Location
      ----                    -----             ----    --------
   profile                dev-readonly           manual    --profile
access_key     ****************ABCD              sso
secret_key     ****************EFGH              sso
    region                us-west-2      config-file    ~/.aws/config

To retrieve a single configuration value, use aws configure get:

$ aws configure get region --profile dev-readonly
us-west-2

How to Switch Profiles Using the AWS CLI

Now that you have your AWS profiles configured, switching between them can be done in three ways. Each method has a different scope and use case.

Method 1: Using the --profile Flag

The --profile flag lets you specify which profile to use for a single command. This is ideal for quick, one-off commands or when you need to run a command against a different account than your current session.

aws s3 ls --profile dev-readonly
aws ec2 describe-instances --profile prod-admin

This method has the highest precedence and will override any profile set via environment variables or configuration files. It's perfect when you need to quickly check something in another account without changing your current session context.

Method 2: Using the AWS_PROFILE Environment Variable

The AWS_PROFILE environment variable sets the default profile for all AWS CLI commands in your current shell session. This is useful when you're doing extended work in a specific environment.

Linux/macOS:

export AWS_PROFILE=staging

Windows PowerShell:

$env:AWS_PROFILE = "staging"

Windows Command Prompt (persistent across sessions):

setx AWS_PROFILE staging

After setting this variable, all subsequent commands use the specified profile without needing the --profile flag:

$ export AWS_PROFILE=staging
$ aws s3 ls
# Lists buckets in the staging account

$ aws ec2 describe-instances
# Shows instances in the staging account

To return to the default profile:

Linux/macOS:

unset AWS_PROFILE

Windows PowerShell:

Remove-Item Env:AWS_PROFILE

Method 3: Editing the Default Profile

You can directly edit the ~/.aws/credentials and ~/.aws/config files to change which profile is treated as default. This method is useful for bulk profile management or when you want a permanent change to your default account.

The default profile is used automatically when no profile is explicitly specified. If you want to change your default working environment, you can either:

1. Rename an existing profile to default
2. Copy the credentials from your preferred profile to the [default] section

Note: In the credentials file, profile names are written WITHOUT the profile prefix. In the config file, all profiles EXCEPT [default] must include the profile prefix (e.g., [profile dev-readonly]).

Understanding Configuration Precedence

The AWS CLI resolves credentials and configuration following a specific priority order. Understanding this helps you troubleshoot when commands use unexpected profiles:

1. Command-line parameters (--profile, --region) - Highest precedence
2. Environment variables (AWS_PROFILE, AWS_REGION)
3. Assume role (via configuration)
4. AWS IAM Identity Center (SSO credentials)
5. Credentials file (~/.aws/credentials)
6. Config file (~/.aws/config)
7. Container credentials (ECS task IAM roles)
8. EC2 instance profile credentials - Lowest precedence

Example of precedence in action:

# Environment variable sets the profile to production
export AWS_PROFILE=production

# But command-line parameter overrides it
aws s3 ls --profile dev-readonly
# This command uses dev-readonly, NOT production

How to Verify Your Active Profile

One of the most common questions when working with multiple profiles is: "Which profile am I currently using?" Here's how to find out.

Using aws configure list

The aws configure list command shows your current configuration and importantly, where each value comes from:

❯ aws configure list
NAME       : VALUE                    : TYPE             : LOCATION
profile    : TTC-NextJS               : env              : ['AWS_PROFILE', 'AWS_DEFAULT_PROFILE']
access_key : ****************UKCM     : env              :
secret_key : ****************X1LX     : env              :
region     : us-east-1                : env              : ['AWS_REGION', 'AWS_DEFAULT_REGION']

The profile row tells you which profile is active. If it shows <not set>, you're using the default profile.

Using aws sts get-caller-identity

For a definitive answer about which AWS identity is being used, run:

$ aws sts get-caller-identity
{
    "UserId": "AIDAEXAMPLEUSERID:dannysteenman",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/AWSReservedSSO_AdministratorAccess_4455eba82126be11/dannysteenman"
}

This command tells you exactly which AWS account and identity your CLI commands will execute as. I recommend creating an alias for this command since you'll use it frequently. Check out how to create an alias to simplify this command.

You can also verify which AWS credentials and permissions are associated with your active profile.

Platform-Specific Profile Switching

Different operating systems have different syntax for setting environment variables. Here's a complete reference for each platform.

Linux and macOS

# Set profile for current session
export AWS_PROFILE=dev-readonly

# Verify the change
echo $AWS_PROFILE

# Unset to return to default
unset AWS_PROFILE

File locations:

• Credentials: ~/.aws/credentials
• Config: ~/.aws/config

Windows PowerShell

# Set profile for current session
$env:AWS_PROFILE = "dev-readonly"

# Verify the change
echo $env:AWS_PROFILE

# Unset to return to default
Remove-Item Env:AWS_PROFILE

File locations:

• Credentials: %UserProfile%\.aws\credentials
• Config: %UserProfile%\.aws\config

Windows Command Prompt

# Set profile for current session only
set AWS_PROFILE=dev-readonly

# Set profile persistently (survives terminal restart)
setx AWS_PROFILE dev-readonly

# Verify the change
echo %AWS_PROFILE%

Note: The setx command makes the environment variable persistent across sessions, while set only affects the current terminal window.

Working with IAM Role Profiles

IAM role profiles let you assume roles for elevated permissions or cross-account access. This is a fundamental pattern in AWS multi-account architectures.

Basic Role Configuration

Role profiles are defined in ~/.aws/config with a role_arn and source_profile:

[profile prod-admin]
role_arn = arn:aws:iam::999999999999:role/AdminRole
source_profile = dev-readonly
region = us-east-1

When you use this profile, the AWS CLI automatically:

1. Retrieves credentials from the source_profile
2. Calls AWS STS AssumeRole to get temporary credentials
3. Uses those temporary credentials for your command
4. Caches the credentials in ~/.aws/cli/cache for reuse

# This automatically assumes the AdminRole
aws s3 ls --profile prod-admin

Cross-Account Role Assumption

For cross-account access, you'll need proper IAM permissions. The user in your source_profile needs sts:AssumeRole permission, and the target role needs a trust relationship allowing the assumption.

[profile cross-account-admin]
role_arn = arn:aws:iam::888888888888:role/CrossAccountAdmin
source_profile = dev-readonly
external_id = UNIQUE_EXTERNAL_ID
region = eu-west-1

The external_id provides additional security for cross-account role assumption. For complex multi-account setups, Service Control Policies can further restrict which roles can be assumed.

For MFA-protected roles:

[profile security-admin]
role_arn = arn:aws:iam::123456789012:role/SecurityAudit
source_profile = default
mfa_serial = arn:aws:iam::123456789012:mfa/john.doe

When using this profile, you'll be prompted for your MFA code:

$ aws sts get-caller-identity --profile security-admin
Enter MFA code for arn:aws:iam::123456789012:mfa/john.doe: 123456
{
    "UserId": "AROAEXAMPLEROLEID:botocore-session-1234567890",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/SecurityAudit/botocore-session-1234567890"
}

Clearing Cached Role Credentials

If your role credentials are revoked or you need to force fresh credential retrieval:

Linux/macOS:

rm -r ~/.aws/cli/cache

Windows:

del /s /q %UserProfile%\.aws\cli\cache

Troubleshooting Common Profile Issues

When profile switching doesn't work as expected, here's how to diagnose and fix the most common issues.

Profile Not Found Errors

Error: The config profile (my-profile) could not be found

Causes and fixes:

1. Typo in profile name: Check the exact profile name with aws configure list-profiles
2. Missing profile prefix: In ~/.aws/config, named profiles must use [profile my-profile] syntax (except [default])
3. Wrong file: Ensure your profile is defined in the correct file. SSO and role configurations go in ~/.aws/config, while IAM credentials go in ~/.aws/credentials

Invalid Credentials or Access Denied

Error: An error occurred (InvalidClientTokenId) or Access Denied

Diagnosis steps:

1. Verify which identity you're using:

aws sts get-caller-identity --profile my-profile

2. If this fails, your credentials may be invalid or expired
3. For IAM users, regenerate the access keys in the IAM console
4. For SSO profiles, re-authenticate with aws sso login --profile my-profile

SSO Token Expiration

Error: The SSO session associated with this profile has expired or is otherwise invalid

Fix: Re-authenticate with your SSO provider:

aws sso login --profile my-sso-profile

Or if using SSO sessions:

aws sso login --sso-session my-sso-session

Pro tip: SSO sessions with sso_registration_scopes = sso:account:access support automated token refresh, reducing how often you need to re-authenticate.

For specific SSO errors, see these troubleshooting guides:

• Fix missing SSO configuration errors
• Resolve SSO GetRoleCredentials errors

Configuration File Syntax Errors

Error: Error parsing config file or unexpected profile behavior

Common syntax issues:

1. Missing profile prefix in config file: Use [profile my-profile] not [my-profile] (except for [default])
2. Extra spaces: Ensure no trailing spaces after values
3. Incorrect indentation: INI files are whitespace-sensitive
4. Comments: Use # for comments, not // or /* */

Validate your config by listing profiles:

aws configure list-profiles

If your profile doesn't appear, there's likely a syntax error in your configuration files.

Alternative Tools for Profile Management

While the AWS CLI provides solid profile management, several open-source tools can streamline your workflow further.

I've been using an open-source tool called Granted CLI, developed by Common-Fate, that makes it easier to manage AWS profiles. Learn more about using Granted CLI to assume IAM roles.

Other popular alternatives include:

• aws-vault: Stores credentials securely in your operating system's keychain and injects them into your shell
• awscli_mate: Provides a simpler interface for profile switching with fuzzy search

Quick Reference: Profile Switching Methods

Here's a comparison of all three methods to help you choose the right one:

My recommendation: Use AWS_PROFILE for your daily work when focusing on a single environment. Use --profile for quick commands against other accounts. Reserve editing the default profile for changing your primary working account.

Conclusion

Switching profiles using the AWS CLI is a vital skill for anyone working with multiple AWS accounts. You now know three methods to switch profiles, how to verify which profile is active, and how to troubleshoot common issues.

Here's the key takeaway: always prefer AWS SSO over IAM user credentials. SSO provides temporary credentials that auto-refresh and don't persist on disk as plaintext. If your system gets compromised, the damage is limited to the current session rather than giving attackers permanent access to your AWS accounts.

For daily work, set AWS_PROFILE to your primary environment and use --profile for quick switches to other accounts. And when things don't work as expected, remember to check aws sts get-caller-identity to verify exactly which identity you're using.

Have questions about managing AWS profiles or multi-account strategies? Drop a comment below.