How to Configure the AWS CLI Multiple Accounts Setup

To configure aws cli multiple accounts management, you should define named profiles in your `~/.aws/credentials` and `~/.aws/config` files using the `aws configure –profile` command. This setup allows you to switch execution contexts seamlessly via the `–profile` flag or by setting the `AWS_PROFILE` environment variable in your terminal session.

Core Concepts: Profiles, Credentials, and Config

For developers, system administrators, and DevOps engineers, working in a multi-account environment is standard practice. You might have one account for local development, another for staging, a third for production, and separate accounts for different clients. Managing these distinct environments programmatically requires configuring the aws cli multiple accounts system. This system allows you to execute commands against different accounts without needing to constantly log in and out or manually swap access keys.

At the heart of the AWS CLI multi-account management are named profiles. A profile is a collection of settings and credentials that define which account and region your commands should target. These configurations are stored locally on your machine in two specific files located in the .aws directory in your user home path: the credentials file and the config file. The credentials file stores sensitive authentication data, such as your access keys and session tokens, while the config file stores non-sensitive parameters like default AWS regions and output formats.

Step-by-Step Configuration Guide

Setting up your machine to handle multiple AWS profiles is straightforward. Follow this step-by-step tutorial to configure named profiles, IAM Identity Center (SSO), and role assumptions.

Prerequisites

• The AWS CLI installed on your local machine (version 2 is highly recommended)
• Valid AWS credentials (Access Key ID and Secret Access Key, or SSO start URL)
• Administrative or developer access to the target AWS accounts

Step 1: Configuring Named Profiles via CLI

To create a new named profile, run the aws configure command followed by the --profile flag and the name you want to assign to the profile. For example, let’s create a development and a production profile:

# Configure the development profile
aws configure --profile development
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json

# Configure the production profile
aws configure --profile production
AWS Access Key ID [None]: AKIAI47SBVWQEXAMPLE
AWS Secret Access Key [None]: qAbCdefGhIjKlMnOpQrStUvWxYzEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: json

Running these commands will automatically create the ~/.aws/credentials and ~/.aws/config files if they do not exist, or append the new profiles if they do.

Step 2: Editing Config and Credentials Files Manually

You can also edit the files directly. Open your terminal and edit the files using your preferred text editor. Here is what your files should look like after manual configuration:

~/.aws/credentials:

[development]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

[production]
aws_access_key_id = AKIAI47SBVWQEXAMPLE
aws_secret_access_key = qAbCdefGhIjKlMnOpQrStUvWxYzEXAMPLEKEY

~/.aws/config:

[profile development]
region = us-west-2
output = json

[profile production]
region = us-east-1
output = json

Note that in the config file, the profile names must be prefixed with the word profile, except for the [default] profile. In the credentials file, only the profile name itself is used.

Step 3: Setting Up AWS IAM Identity Center (SSO)

For enterprise environments, using static access keys is discouraged due to security risks. Instead, configure AWS IAM Identity Center (SSO) profiles to use temporary, short-lived credentials:

# Initialize SSO configuration
aws sso configure --profile enterprise-dev
SSO start URL [None]: https://my-organization.awsapps.com/start
SSO region [None]: us-east-1
# Follow the browser prompts to authenticate...
# Select the AWS account and role assigned to you
CLI default client Region [None]: us-east-1
CLI default output format [None]: json

This creates an SSO-enabled profile in your config file. When you execute a command, the AWS CLI checks if your session is active; if not, it automatically opens your web browser for authentication, caches the credentials locally, and proceeds with the command.

Step 4: Configuring Cross-Account Role Assumption

If you authenticate to a central “master” account and assume roles in target client accounts, configure profile chaining in your ~/.aws/config file:

[profile master]
region = us-east-1
output = json

[profile client-prod]
role_arn = arn:aws:iam::123456789012:role/AgencyAdminRole
source_profile = master
region = us-east-1
output = json

In this setup, when you run a command targeting client-prod, the AWS CLI uses the credentials from the master profile to make an STS AssumeRole API call, retrieves temporary credentials for the target role, and executes your command.

Practical Execution and Shell Customizations

Once your profiles are set up, you need efficient ways to use them in your daily development workflow. There are two primary methods for running commands against a specific profile.

First, use the --profile flag directly in your commands:

# List S3 buckets in the development account
aws s3 ls --profile development

# Describe EC2 instances in the production account
aws ec2 describe-instances --profile production

Second, set the AWS_PROFILE environment variable. This changes the active profile for your entire terminal session, so you do not need to append the profile flag to every command:

# Switch session to production
export AWS_PROFILE=production
aws s3 ls  # Executes against production

# Switch session to development
export AWS_PROFILE=development
aws lambda list-functions  # Executes against development

To switch profiles even faster, add a helper function to your ~/.bashrc or ~/.zshrc file:

# AWS Profile Switcher Function
aws-switch() {
    export AWS_PROFILE=$1
    echo "Switched terminal to AWS profile: $AWS_PROFILE"
    aws sts get-caller-identity --query "Account" --output text
}

Comparison Matrix: CLI Profile Methods

Execution Method	Setup Effort	Best For	Security Level
–profile Flag	None (Built-in)	One-off quick commands	High (Explicit target)
AWS_PROFILE Env Var	Low (Single command)	Extended work in one account	Medium (Easy to run in wrong account if forgotten)
SSO Integrations	Medium (Requires Identity Center)	Enterprise environments	Maximum (No static local credentials)
Role Assumption	Medium (Requires IAM trust setup)	Multi-account agency workflows	Very High (Short-lived session tokens)

Security Protocols for Local AWS Credentials

Securing your local credentials is critical. If your machine is compromised, attackers can easily read your ~/.aws/credentials file and steal your access keys. First, always restrict the permissions of your .aws folder. On macOS and Linux, run chmod 600 ~/.aws/credentials to ensure only your local user account can read the file. On Windows, modify the file security settings to restrict access. Second, avoid checking any configuration files containing access keys into version control systems like Git. Finally, enforce Multi-Factor Authentication (MFA) for sensitive accounts, especially when assuming production roles, forcing the CLI to prompt for an MFA token before executing commands.

Bridging the Terminal and the Browser: AWS Console Management

DevOps workflows often require using both the command line and the AWS Management Console simultaneously. When managing multiple accounts, this leads to a frustrating browser experience. Standard browsers share cookies across tabs, meaning you cannot log into the AWS Console for account A and account B at the same time in the same browser. You are forced to use private tabs, different browsers, or constantly log in and out, which is slow and triggers security blocks.

This is where browser-level isolation is invaluable. For teams who need to manage managing multiple accounts safely, standard browsers fall short. If you also manage other cloud business lines, like e-commerce, separating your infrastructure is just as important as running safe multi-store operations on retail networks. To find the right tool for this level of security, you should review the best browser for multiple accounts. For specialized setups like AWS e-commerce integrations, you can also consult our guide on managing multiple Amazon accounts to ensure your operations are secure across all platform levels.

How Send.win Streamlines AWS Console Access

Send.win is a multi-account browser platform designed to solve console login conflicts. It offers two modes of operation: the Sendwin Browser (a native desktop client for Windows, macOS, and Linux) and cloud browser sessions (which run in the cloud with no local installation required). With Send.win, you can open a separate, sandboxed browser profile for each AWS account. This allows you to view the development console, staging console, and production console side-by-side in separate tabs without any cookie overlap or session confusion.

Send.win offers a 30-day free trial with no credit card required, letting you test its features. Upgrading to the Pro plan costs $9.99/month ($6.99/month when billed annually), while the Team plan costs $29.99/month ($20.99/month when billed annually). The Pro plan includes a local Automation API that lets developers use Puppeteer, Playwright, or Selenium to automate AWS console tasks securely. Using Send.win alongside your CLI profiles provides the ultimate secure environment for multi-account AWS management.

Frequently Asked Questions

How do I list all configured AWS CLI profiles?

To see all the profiles configured on your machine, run the command aws configure list-profiles. This reads your ~/.aws/config file and prints the names of all profiles. Alternatively, you can open the config file in a text editor to view all profile names and their associated settings.

Can I run commands on multiple profiles at the same time?

Yes, because the AWS CLI executes commands in isolated processes. You can open multiple terminal tabs or windows, set a different AWS_PROFILE environment variable in each window, and run commands simultaneously without any cross-account contamination or conflict.

What is the best way to switch between AWS profiles quickly?

The best way is to use a shell function or alias in your shell configuration file (like .zshrc or .bashrc). You can also use popular open-source command-line utilities like awsp (AWS Profile Switcher), which provides an interactive list in your terminal to select and activate profiles.

How do I troubleshoot the “ExpiredToken” error?

This error occurs when you use temporary credentials (from SSO or role assumption) that have expired. To fix this, run the command aws sso login --profile [profile_name] to re-authenticate and refresh your credentials cache, or re-run your STS assume-role script.

Why is my default profile being ignored?

If the CLI is ignoring your default profile, check if the AWS_PROFILE environment variable is set in your current shell session. The environment variable takes precedence over the config file, so if it is set, the CLI will use that profile instead of the default one. Run unset AWS_PROFILE to restore default behavior.

Is it secure to check ~/.aws files into Git?

No, you should never check your ~/.aws configuration or credentials files into version control systems like Git. These files contain highly sensitive credentials and access keys. If committed, anyone with access to the repository can steal your keys and compromise your AWS infrastructure.

How does Sendwin Browser help with AWS multi-account management?

Sendwin Browser allows you to open separate, sandboxed browser sessions for each AWS account Console. This isolates cookies and session data per tab, allowing you to log into different AWS accounts simultaneously without session conflicts, making web-based AWS management clean and secure.

Conclusion

Configuring the AWS CLI for multiple accounts is an essential step toward building a mature DevOps workflow. By using named profiles, SSO integrations, and role assumption, you can switch contexts seamlessly and execute commands safely. When combined with browser isolation tools like Send.win for console access, you establish a secure, efficient environment that protects your cloud infrastructure from accidental mistakes and security threats.