How to Configure AWS CLI Profiles for Multiple Accounts

Quick answer

Give each AWS account or role its own named CLI profile rather than replacing the credentials in your default profile. Create one like this:

aws configure --profile development

At the prompts, enter the access key, secret key, default Region, and output format. To run a command with that profile, add --profile:

aws sts get-caller-identity --profile development

If you want the same profile active for a whole terminal session, set the AWS_PROFILE environment variable.

# Linux or macOS
export AWS_PROFILE=development

# Windows PowerShell
$env:AWS_PROFILE = 'development'

Before you change any resources, run aws sts get-caller-identity. The response shows the active account ID and the user or assumed role. It’s a quick check that can keep you from making changes in the wrong AWS account.

For workforce access, IAM Identity Center is safer than keeping long-lived access keys around. Set it up with aws configure sso --profile company-development, then sign in using aws sso login --profile company-development.

What AWS CLI profiles do

An AWS CLI profile is a named set of authentication and configuration settings. With separate profiles, one workstation can connect to development, staging, production, and customer accounts without someone repeatedly editing credentials. Less swapping, fewer surprises.

The AWS CLI normally keeps profile data in two files:

What you’ll need

• AWS CLI version 2, installed and available from your terminal.
• Permission to access the AWS accounts you need.
• One supported way to authenticate: an IAM Identity Center assignment, access keys, or permission to assume an IAM role.
• A default AWS Region chosen for each profile.

Check the installed version before going further:

aws --version

Set up profiles with access keys

IAM users can authenticate this way. Still, temporary credentials or IAM Identity Center are usually the better choice when they’re available.

1. Create the first named profile:

   aws configure --profile development

2. Enter the values requested by the CLI:

   AWS Access Key ID: YOUR_ACCESS_KEY
   AWS Secret Access Key: YOUR_SECRET_KEY
   Default region name: us-east-1
   Default output format: json

3. Repeat the command with different names for the other profiles:

   aws configure --profile staging
   aws configure --profile production

4. See which profiles are available:

   aws configure list-profiles

5. Then verify the identity behind each one:

   aws sts get-caller-identity --profile development
   aws sts get-caller-identity --profile production

Once generated, the credentials file may look something like this:

[development]
aws_access_key_id = EXAMPLEDEVELOPMENTKEY
aws_secret_access_key = EXAMPLEDEVELOPMENTSECRET

[production]
aws_access_key_id = EXAMPLEPRODUCTIONKEY
aws_secret_access_key = EXAMPLEPRODUCTIONSECRET

Don’t paste real credentials into documentation, support tickets, chat messages, or source control. Secrets in the credentials file aren’t encrypted, so the file should be readable only by the local user.

Set up profiles with IAM Identity Center

AWS IAM Identity Center uses browser-based sign-in and issues temporary credentials. You’ll need AWS CLI version 2 for the current SSO workflow.

1. Start the interactive setup:

   aws configure sso --profile company-development

2. Enter the SSO start URL or session details from your administrator. Then select the AWS account and role, and choose a default Region.

3. Sign in through the browser:

   aws sso login --profile company-development

4. Check the active identity:

   aws sts get-caller-identity --profile company-development

Cached sessions eventually expire. When that happens, run aws sso login again. To clear the cached SSO sessions instead, use:

aws sso logout

Set up a profile that assumes an IAM role

A role profile gets temporary credentials through another profile, which acts as its credential source. This works well when one base identity has permission to assume roles across multiple accounts.

Add entries like these to ~/.aws/config:

[profile base-user]
region = us-east-1
output = json

[profile production-admin]
role_arn = arn:aws:iam::123456789012:role/ProductionAdmin
source_profile = base-user
region = us-east-1
output = json

Keep the base-user credentials in ~/.aws/credentials:

[base-user]
aws_access_key_id = EXAMPLEKEY
aws_secret_access_key = EXAMPLESECRET

Now test the assumed role:

aws sts get-caller-identity --profile production-admin

Both sides have to allow the request. The role’s trust policy must permit the base identity to assume it, and that base identity needs sts:AssumeRole permission.

Switch between AWS CLI profiles

Use a profile for one command

aws s3 ls --profile development

Use a profile in the current terminal

# Linux or macOS
export AWS_PROFILE=production-admin

# Windows PowerShell
$env:AWS_PROFILE = 'production-admin'

Go back to the default profile

# Linux or macOS
unset AWS_PROFILE

# Windows PowerShell
Remove-Item Env:AWS_PROFILE

Command-line options generally take precedence over settings saved in a profile. Environment variables may override those profile values too, so if the CLI reports an identity you weren’t expecting, look for old AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN variables.

Mistakes that cause trouble

• Editing the wrong file. Access keys usually go in credentials. Role and Region settings belong in config.
• Using the wrong section names. In the config file, write [profile development]. The credentials file uses [development].
• Keeping expired session variables active. Exported credentials can take precedence even after you’ve selected a profile.
• Depending on the default profile. Explicit profile names make production commands and scripts easier to audit later.
• Skipping the identity check. A profile name may look familiar and still point to an account you didn’t expect.

Safer habits for multiple accounts

• Prefer IAM Identity Center or temporary role credentials instead of long-lived IAM user keys.
• Choose names that say what the profile is for, such as company-production-readonly.
• Grant the least privilege required. If write access isn’t needed, use a read-only role.
• Never commit the .aws directory to Git.
• Before a deployment, deletion, or infrastructure change, confirm the account ID and ARN.
• For production sessions, use separate terminal tabs or make the active account visible in your shell prompt.

Check the finished setup

Run the following commands for every profile you create:

aws configure list --profile development
aws sts get-caller-identity --profile development
aws ec2 describe-regions --profile development --output table

If all three commands succeed, check the identity output one more time. Once it shows the account ID you expected, the AWS CLI profile is ready.