Configure and Switch Between Multiple AWS CLI Profiles

If you work with multiple AWS accounts, you do not need to run aws configure again every time you switch accounts. AWS CLI named profiles keep separate configuration for environments such as dev and prod, then let you choose the one you want with --profile or AWS_PROFILE.

The important part is verifying which identity the CLI actually selected before a command touches production. Every profile switch in this guide is checked with aws sts get-caller-identity, which shows the active AWS account and IAM user or role.

Quick Answer: Switch Between AWS CLI Profiles

Create a separate named profile for each AWS account, role, or authentication setup you need to select. In this example, dev and prod point at two different AWS accounts.

Create the profiles:

aws configure --profile dev

Add a second profile for the production account:

aws configure --profile prod

Use one profile for one command:

aws sts get-caller-identity --profile prod

Or make it the profile for this shell:

export AWS_PROFILE=prod

Confirm the active account before running anything destructive:

aws sts get-caller-identity

The sections below show where profiles are stored, how SSO and role profiles work, and how to avoid credential conflicts when switching accounts.

Create Multiple AWS CLI Profiles

Create dev and prod profiles

For access-key-based profiles, AWS CLI commonly stores credentials and configuration in two shared files:

This layout applies to the access-key example below. SSO and role-based profiles work differently and may not store long-lived credentials in ~/.aws/credentials.

Profile sections use different syntax in each file:

• Credentials file: [profile-name] without a profile prefix
• Config file: [profile profile-name] with the profile prefix (except [default])

Create a profile interactively for the dev account:

aws configure --profile dev

The prompts look like this:

AWS Access Key ID [None]: ...
AWS Secret Access Key [None]: ...
Default region name [None]: ap-south-1
Default output format [None]: json

aws configure is asking for credentials and defaults for this named profile. The access key ID identifies the AWS credential being used, while the secret access key is used to cryptographically sign API requests. Together, they authenticate the IAM user associated with those credentials. The Region becomes the default for regional AWS services unless you override it on a command. json controls how AWS CLI displays command output; it does not affect authentication or which account is selected.

Repeat for production:

aws configure --profile prod

The access key and secret go into the credentials file; Region and output format go into the config file under [profile dev] and [profile prod].

Where AWS stores named profiles

List every profile name the CLI can see:

aws configure list-profiles

dev
prod
audit

A multi-account layout looks like this (secrets replaced with placeholders):

--- ~/.aws/credentials ---
[dev]
aws_access_key_id = AKIADEVKEYEXAMPLE
aws_secret_access_key = ***

[prod]
aws_access_key_id = AKIAPRODKEYEXAMPLE
aws_secret_access_key = ***

--- ~/.aws/config ---
[profile dev]
region = ap-south-1
output = json

[profile prod]
region = ap-south-1
output = json

[profile audit]
region = ap-south-1
output = json
role_arn = arn:aws:iam::222222222222:role/audit-readonly
source_profile = prod

Never commit AWS credential files to source control. If ~/.aws/credentials contains long-lived access keys, ensure the file is readable only by your user, for example with chmod 600 ~/.aws/credentials. Prefer short-term credentials instead of storing long-lived access keys when possible.

Optional: use an SSO profile

A named profile does not have to contain long-lived access keys. It can also point to an IAM Identity Center configuration:

aws configure sso --profile prod-sso

Sign in through the browser flow:

aws sso login --profile prod-sso

Confirm the SSO session with the same profile name:

aws sts get-caller-identity --profile prod-sso

Here, prod-sso is just another named profile. The difference is how it obtains credentials: through IAM Identity Center rather than access keys stored in ~/.aws/credentials. Once authenticated, switch and verify SSO profiles with the same --profile or AWS_PROFILE techniques used elsewhere in this guide.

Use a Profile for One AWS CLI Command

Pass --profile when a single command should use a named profile without changing the shell default:

aws sts get-caller-identity --profile prod

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "222222222222",
    "Arn": "arn:aws:iam::222222222222:user/prod-admin"
}

Inspect what that one invocation loads:

aws configure list --profile prod

NAME       : VALUE                    : TYPE             : LOCATION
profile    : prod                     : manual           : --profile
access_key : ****************5TGM     : shared-credentials-file :
secret_key : ****************Iwdx     : shared-credentials-file :
region     : ap-south-1               : config-file      : ~/.aws/config

The LOCATION column confirms keys came from the shared credentials file, not from exported environment variables. --profile is usually safer for scripts and one-off administrative commands because the intended profile is visible directly in the command instead of depending on the shell's current environment.

Switch the AWS Profile for Your Shell

Export AWS_PROFILE when every command in the session should share one profile:

export AWS_PROFILE=prod

Confirm the shell picked it up:

aws sts get-caller-identity

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "222222222222",
    "Arn": "arn:aws:iam::222222222222:user/prod-admin"
}

The configure list output shows where each value was resolved:

aws configure list

NAME       : VALUE                    : TYPE             : LOCATION
profile    : prod                     : env              : ['AWS_PROFILE', 'AWS_DEFAULT_PROFILE']
access_key : ****************5TGM     : shared-credentials-file :
secret_key : ****************Iwdx     : shared-credentials-file :
region     : ap-south-1               : config-file      : ~/.aws/config

Here, AWS_PROFILE selects prod, while the access key still comes from ~/.aws/credentials. The TYPE and LOCATION columns make it easy to see where each value came from.

To return to the implicit default profile:

unset AWS_PROFILE AWS_DEFAULT_PROFILE

Add AWS_PROFILE to .bashrc, .zshrc, or another shell startup file only if you really want that profile selected every time you open a shell. On machines used with several AWS accounts, setting it manually is safer because the active account is less likely to be forgotten.

Check Which AWS Profile and Account Are Active

Three checks answer different questions:

Show the profile name the environment variable selected:

echo "$AWS_PROFILE"

prod

echo "$AWS_PROFILE" shows only the profile name selected through that environment variable. It does not prove which AWS identity will sign the next request.

Inspect how the CLI resolved settings:

aws configure list

Read the TYPE and LOCATION columns for the access_key and secret_key rows. If the credential source shows env, exported environment variables are supplying the credentials even though the profile row says prod.

To verify which IAM user or role is authenticating the request:

aws sts get-caller-identity

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "222222222222",
    "Arn": "arn:aws:iam::222222222222:user/prod-admin"
}

$AWS_PROFILE tells you which profile name was selected through the environment. get-caller-identity verifies the AWS account and IAM user or role that authenticated the request. Run it with the same --profile, AWS_PROFILE, and AWS_* environment variables as the command that follows — especially before terraform apply, aws s3 rm, or other destructive work.

To compare dev and prod in one shell, clear overrides first:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

Switch to dev and verify the account ID changes:

export AWS_PROFILE=dev

The response should show the dev account:

aws sts get-caller-identity

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "111111111111",
    "Arn": "arn:aws:iam::111111111111:user/dev-admin"
}

Switch to prod and verify again:

export AWS_PROFILE=prod

The account ID should move to production:

aws sts get-caller-identity

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "222222222222",
    "Arn": "arn:aws:iam::222222222222:user/prod-admin"
}

When the Account matches but the Arn does not, the CLI is authenticated as a different IAM path than expected — common with role sessions and SSO permission sets. Read the full Arn, not only the 12-digit account ID. For a deeper provider walkthrough, see Which credentials AWS CLI uses.

How AWS CLI Profile and Credential Precedence Works

Selecting a profile and selecting credentials are two related steps. The profile tells AWS CLI which named configuration to use, while the credential provider determines how the CLI authenticates the request. Start with how the profile name was chosen:

              How was the profile selected?
                         |
          +--------------+--------------+
          |              |              |
          v              v              v
   --profile prod   AWS_PROFILE=prod   neither
          |              |              |
          v              v              v
 explicit profile   shell-selected     [default]
                    profile
          |              |
          v              v
 credentials for    credentials for
 "prod" profile     "prod" profile
 (explicit          (exported
  profile)           AWS_ACCESS_KEY_ID
                     can override file
                     keys in "prod")

A profile is only a named configuration. The CLI still needs credentials to authenticate the request. Those credentials might come from access keys, IAM Identity Center, an assumed role, or another supported AWS credential provider.

--profile versus AWS_PROFILE

Both select a named profile, but they are not equivalent for every edge case.

Profile name precedence: --profile on the command line wins over AWS_PROFILE. If AWS_PROFILE=prod is set but the command includes --profile dev, the CLI explicitly uses the dev profile for that invocation.

Set the shell default to prod first:

export AWS_PROFILE=prod

Then override it for one command with --profile dev:

aws sts get-caller-identity --profile dev

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "111111111111",
    "Arn": "arn:aws:iam::111111111111:user/dev-admin"
}

The identity follows dev from --profile, not prod from the environment.

AWS_PROFILE versus exported credential variables

When the profile is selected through AWS_PROFILE, explicit credential environment variables can override credentials stored in that profile. AWS documents this case for environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.

This pattern is different from passing --profile on the command line. An explicitly supplied CLI profile is a command-line setting; Botocore resolves credentials through the named profile's configured providers rather than treating exported access keys as an override of that explicit selection.

You normally would not mix a profile name from one account with exported credentials from another. That situation often happens unintentionally after a CI script, credential helper, or temporary shell setup exported AWS_ACCESS_KEY_ID and related variables.

Example with AWS_PROFILE only:

export AWS_PROFILE=dev

Export prod account keys on top of the dev profile name:

export AWS_ACCESS_KEY_ID=AKIAPRODKEYEXAMPLE
export AWS_SECRET_ACCESS_KEY='***'

Check what the CLI will send:

aws configure list

NAME       : VALUE                    : TYPE             : LOCATION
profile    : dev                      : env              : ['AWS_PROFILE', 'AWS_DEFAULT_PROFILE']
access_key : ****************5TGM     : env              :
secret_key : ****************Iwdx     : env              :
region     : ap-south-1               : config-file      : ~/.aws/config

STS signs the request with the exported keys, not the dev profile file:

aws sts get-caller-identity

{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "222222222222",
    "Arn": "arn:aws:iam::222222222222:user/prod-admin"
}

The profile row still says dev, but the Arn shows the prod user because environment keys override file-based credentials when the profile was selected through AWS_PROFILE. Clear overrides before trusting a profile switch:

unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

Use a Profile to Assume an IAM Role

A profile can assume an IAM role in another account or the same account. The config profile references a role_arn and a source_profile that holds credentials allowed to call sts:AssumeRole:

[profile audit]
region = ap-south-1
output = json
role_arn = arn:aws:iam::222222222222:role/audit-readonly
source_profile = prod

The prod profile must belong to an IAM user or role trusted by audit-readonly, and that identity needs sts:AssumeRole on the role ARN.

Think of source_profile as the identity AWS CLI starts with. Here, AWS CLI first authenticates using the prod profile, then uses that identity to request temporary credentials for the audit-readonly role. This example uses the existing prod identity to switch into a more restricted read-only role in the same account.

        prod profile
             |
             | authenticate as the source identity
             v
        STS AssumeRole
             |
             | returns temporary credentials
             v
      audit-readonly role

Call the role profile like any other named profile:

aws sts get-caller-identity --profile audit

{
    "UserId": "AROAXXXXXXXXXXXXXXXXX:botocore-session-1790561406",
    "Account": "222222222222",
    "Arn": "arn:aws:sts::222222222222:assumed-role/audit-readonly/botocore-session-1790561406"
}

The output confirms that the request is using an assumed-role session. The Arn contains assumed-role/audit-readonly/..., while UserId identifies the role session. get-caller-identity does not display the temporary access key, secret key, or session token — only identity metadata.

Run aws configure list --profile audit to inspect how the profile resolved its temporary credentials. For role and SSO profiles, AWS CLI can display the temporarily cached access key and secret key used for that session. The same verification step also works with SSO and other temporary credential methods: authenticate or refresh the credentials, then run aws sts get-caller-identity.

  dev profile  ──→ AWS account 111111111111
 prod profile  ──→ AWS account 222222222222
audit profile  ──→ AssumeRole ──→ prod account (read-only role)

Safely Switch Between AWS Accounts

Before production changes:

1. unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN when switching away from CI-style exports
2. Set export AWS_PROFILE=<name> or pass --profile on the command
3. Run aws sts get-caller-identity and read Account and Arn
4. Run aws configure list if the identity still looks wrong — check LOCATION for env versus shared-credentials-file

Terraform uses the same files but resolves credentials through the AWS provider. When terraform plan targets the wrong account, align AWS_PROFILE and any profile argument in the provider block — see Fix Terraform AWS credentials error.

Troubleshooting AWS CLI Profiles

Summary

Named profiles let one workstation keep separate AWS CLI configurations for different accounts, roles, or authentication methods. Access-key profiles commonly use ~/.aws/credentials for credentials and ~/.aws/config for settings such as Region and role configuration. Use aws configure list-profiles to see valid names, --profile for a single command, and AWS_PROFILE for a session default.

If --profile and AWS_PROFILE specify different profiles, --profile takes precedence for that command. When a profile is selected with AWS_PROFILE, exported variables such as AWS_ACCESS_KEY_ID can still override credentials stored in that profile. Using an explicit --profile name tells AWS CLI to resolve credentials through that named profile for the command. Role profiles add role_arn and source_profile; the active principal shows as an assumed-role ARN after STS succeeds.

Make aws sts get-caller-identity part of every switch — read Account and the full Arn before destructive API calls. When keys are missing or rejected outright, use the dedicated troubleshooting guides for Unable to locate credentials and InvalidClientTokenId rather than guessing at profile names.

References

• AWS CLI — Authentication and access credentials
• AWS CLI — Configuration and credential file settings
• AWS CLI — Using profiles
• AWS CLI — Using an IAM role in the AWS CLI
• AWS CLI — IAM Identity Center authentication
• AWS CLI — Environment variables
• AWS STS — GetCallerIdentity