Master DevOps Tools & Best Practices - DevOps Knowledge Hub Master DevOps Tools & Best Practices - DevOps Knowledge Hub

How to Configure and Manage Multiple AWS CLI Profiles Efficiently

Learn to efficiently manage multiple AWS accounts and environments using AWS CLI named profiles. This guide provides step-by-step instructions on configuring, switching between, and securing different sets of AWS credentials and settings. Optimize your cloud workflow by mastering profile management for enhanced productivity and security.

How to Configure and Manage Multiple AWS CLI Profiles Efficiently

AWS CLI profiles keep your accounts, roles, regions, and output settings separated. If you manage dev, staging, and production from the same laptop, profiles help you avoid running a command against the wrong AWS account.

The goal is simple: make the intended account explicit, reduce long-lived credentials where you can, and give yourself quick checks before destructive commands.

Setting Up Your AWS CLI Configuration File

The AWS CLI stores profile settings in two shared files:

  • ~/.aws/credentials for access keys and session credentials.
  • ~/.aws/config for region, output format, role settings, and other CLI options.

On Windows, the same files live under %USERPROFILE%\.aws\.

Default Profile

When you run aws configure without --profile, it writes settings for [default]. The CLI uses this profile when you do not specify another one and no relevant environment variable overrides it.

# Example of a default profile in ~/.aws/credentials
[default]
aws_access_key_id = YOUR_DEFAULT_ACCESS_KEY
aws_secret_access_key = YOUR_DEFAULT_SECRET_KEY

# Example of a default profile in ~/.aws/config
[default]
region = us-east-1
output = json

Creating Named Profiles

You can create named profiles with aws configure --profile:

aws configure --profile dev
aws configure --profile prod

You can also edit the files directly. Use plain profile names in ~/.aws/credentials:

~/.aws/credentials:

[default]
aws_access_key_id = YOUR_DEFAULT_ACCESS_KEY
aws_secret_access_key = YOUR_DEFAULT_SECRET_KEY

[prod]
aws_access_key_id = YOUR_PROD_ACCESS_KEY
aws_secret_access_key = YOUR_PROD_SECRET_KEY

[dev]
aws_access_key_id = YOUR_DEV_ACCESS_KEY
aws_secret_access_key = YOUR_DEV_SECRET_KEY

In ~/.aws/config, named profiles use the profile prefix:

~/.aws/config:

[default]
region = us-east-1
output = json

[profile prod]
region = us-west-2
output = text

[profile dev]
region = eu-central-1
output = json

Important details:

  • When defining profiles in ~/.aws/config, you must prefix the profile name with profile (e.g., [profile prod]). This is different from ~/.aws/credentials, where you use just the profile name (e.g., [prod]).
  • The [default] profile does not automatically act as a parent for named profiles. If prod needs a region, set region under [profile prod] or provide it another way.

Switching Between Profiles

Once your named profiles are set up, you can use them by specifying the --profile option with your AWS CLI commands.

Example: To list S3 buckets in your production account:

aws s3 ls --profile prod

Example: To describe EC2 instances in your development account:

aws ec2 describe-instances --profile dev

Before you run a risky command, verify who you are:

aws sts get-caller-identity --profile prod

That returns the account ID and ARN for the credentials the CLI is using.

Setting a Default Profile for the Environment

Constantly typing --profile can be tedious. You can set AWS_PROFILE for your current shell session.

Linux/macOS:

export AWS_PROFILE=prod

# Now, commands will use the 'prod' profile by default
aws s3 ls
aws ec2 describe-instances

To unset it:

unset AWS_PROFILE

Windows Command Prompt:

set AWS_PROFILE=prod

# Now, commands will use the 'prod' profile by default
aws s3 ls

To unset it:

set AWS_PROFILE=

Windows PowerShell:

$env:AWS_PROFILE = "prod"

# Now, commands will use the 'prod' profile by default
aws s3 ls

To unset it:

Remove-Item Env:\AWS_PROFILE

Command line options have higher precedence than environment variables. If AWS_PROFILE=dev is set but you run aws s3 ls --profile prod, the command uses prod.

Managing Multiple AWS Accounts with Profiles

Profiles are useful for:

  • Development vs. Production: Keeping your development and production environments separate for safety.
  • Different Teams/Projects: Isolating resources and permissions for distinct teams or projects.
  • Cross-Account Access: If you are an administrator or developer who needs to manage resources in multiple accounts.

Best Practice: Using IAM Roles

Avoid storing long-lived access keys for every account. A common pattern is to keep one source profile or SSO profile, then assume roles into target accounts.

For role assumption, configure a profile like this:

# ~/.aws/config

[profile dev-role]
role_arn = arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME
source_profile = default
region = us-east-1
output = json

When you run a command with --profile dev-role, the CLI uses the default profile to call AWS STS, assumes the role, and uses temporary credentials for the command.

If your organization uses IAM Identity Center, your profile may use SSO settings instead of access keys:

[profile sandbox]
sso_start_url = https://example.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = DeveloperAccess
region = us-east-1
output = json

Then authenticate with:

aws sso login --profile sandbox

Advanced Configuration Options

Beyond credentials and region, profiles can specify other AWS CLI settings:

  • output: json, text, table
  • region: e.g., us-east-1
  • s3.max_concurrent_requests: Number of parallel requests for S3 operations.
  • s3.max_queue_size: Size of the queue for S3 multipart uploads.
  • cli_binary_format: How binary parameters are interpreted in AWS CLI v2.

Example: Configuring S3 settings for a specific profile

Use aws configure set to avoid indentation mistakes:

aws configure set s3.max_concurrent_requests 20 --profile s3-optimized
aws configure set s3.max_queue_size 10000 --profile s3-optimized

That writes S3 settings under the profile in ~/.aws/config:

# ~/.aws/config

[profile s3-optimized]
region = us-east-1
output = json
s3 =
    max_concurrent_requests = 20
    max_queue_size = 10000

Tips and Best Practices

  • Use Descriptive Profile Names: Make your profile names clear and indicative of the account or environment they represent (e.g., prod-admin, dev-web, sandbox-research).
  • Secure Your Credentials: Never commit your ~/.aws/credentials file to version control. Use IAM roles for cross-account access whenever possible to avoid storing long-lived access keys.
  • Regularly Review Access Keys: If you must use access keys, rotate them periodically and disable old ones.
  • Leverage Environment Variables: Use AWS_PROFILE for temporary switching or for CI/CD pipelines where you need to target specific accounts.
  • Watch credential environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN can override credentials from profiles. Clear them if the CLI appears to use the wrong identity.
  • Name profiles by blast radius: Names like prod-readonly, prod-admin, and sandbox-dev are safer than vague names like main or test.

Practical Takeaway

Use profiles for every account and role you touch often, and check aws sts get-caller-identity before changing production resources. Prefer SSO or role-based profiles over long-lived access keys, and keep environment variables in mind when a command seems to target the wrong account.