We have all been there. You are in the zone, debugging a critical issue. You run a command to update a Lambda function or delete an S3 bucket, thinking you are in your dev environment. A split second later, you realize your terminal session was still pointing to production.
As cloud engineers and developers, we rarely work with just a single AWS account. Whether you are managing separate environments (Dev/Staging/Prod), juggling multiple client projects, or simply keeping your personal sandbox separate from work, switching contexts effectively is a survival skill.
Hardcoding credentials into scripts or constantly running aws configure to overwrite your keys isn’t just inefficient—it’s a security risk waiting to happen.
In this guide, you will learn how to master AWS CLI Named Profiles. We will move beyond the default profile and set up a clean, secure system that lets you switch between AWS accounts and roles with a single command. By the end of this post, you’ll be able to manage credentials like a pro, ensuring you never accidentally deploy resources to the wrong environment again.
Table of Contents
Prerequisites
Before we dive into the configuration, make sure you have the following ready:
- AWS CLI Installed (v2 recommended). You need the AWS Command Line Interface installed on your machine.
- Check if it’s installed: Run
aws --versionin your terminal. - If not installed: Follow the official AWS installation guide.
- Check if it’s installed: Run
- IAM Credentials for Two Contexts. To truly test this setup, you will need access to two different IAM users (or at least two distinct sets of credentials). These could be:
- Work Account: Your primary day-to-day credentials.
- Staging/Personal Account: A secondary set of credentials to practice switching.
- Requirement: You will need the Access Key ID and Secret Access Key for both.
- Terminal Access: We will be using standard shell commands. Any modern terminal will work:
- Mac/Linux: Bash or Zsh.
- Windows: PowerShell or Command Prompt.
Understanding the AWS Config Files
Before running commands, it is crucial to understand where the AWS CLI stores your secrets. When you configure the CLI, it doesn’t just hold that information in memory; it writes to two specific plain-text files on your local machine.
Depending on your operating system, these files are located in a hidden folder named .aws:
- Linux & macOS:
~/.aws/ - Windows:
%USERPROFILE%\.aws\
Inside this folder, you will find two files:
credentials: This file stores your sensitive keys (Access Key ID and Secret Access Key). It should be kept secure.
config: This file stores non-sensitive configuration settings, such as your preferred AWS Region (e.g., us-east-1) and output format (e.g., json).
Step 1: Setting up the Default Profile
If you have never run the CLI before, you need to establish a “Default Profile.” This is the profile the CLI uses whenever you run a command without specifying a user.
- Open your terminal and run:
aws configure - Paste your keys when prompted (input is hidden for security):
Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: jsonOnce completed, you have a default profile. If you run aws s3 ls right now, it will use these credentials.
Step 2: Creating Named Profiles
Now, let’s add a second account—perhaps for Production or a Client Project—without overwriting your default credentials. We do this by creating a “Named Profile.”
Method A: The CLI Command (Easiest)
You can use the same configuration command with the --profile flag. Let’s call this profile prod-user.
aws configure --profile prod-userEnter the credentials specific to your production environment. The CLI automatically appends these to your config files.
Method B: Manual Editing (Fastest for Bulk)
If you are comfortable editing text files, you can open ~/.aws/credentials In your favorite code editor (like VS Code or Vim), add the block manually.
File: ~/.aws/credentials
[default]
aws_access_key_id = AKIA_DEFAULT_KEY...
aws_secret_access_key = SECRET_KEY_1...
[prod-user]
aws_access_key_id = AKIA_PROD_KEY...
aws_secret_access_key = SECRET_KEY_2...File: ~/.aws/config
[default]
region = us-east-1
output = json
[profile prod-user]
region = us-west-2
output = jsonNote: In the config file, named profiles must be prefixed with the word profile (e.g., [profile prod-user]), whereas in the credentials file, you just use the name (e.g., [prod-user]).
Step 3: Using & Switching Profiles
Now that you have multiple profiles, how do you use them? You have two main options depending on your workflow.
Option 1: The --profile Flag (Good for one-off commands)
If you just need to run a single command in your production account, append the flag to the command.
# List buckets in the default account
aws s3 ls
# List buckets in the production account
aws s3 ls --profile prod-userOption 2: Environment Variables (Best for active sessions)
If you are going to be working in the production account for the next hour, typing --profile prod-user every time is tedious and error-prone. Instead, you can switch your entire terminal session to use that profile temporarily.
On Mac/Linux:
export AWS_PROFILE=prod-userOn Windows (PowerShell):
$Env:AWS_PROFILE="prod-user"Once you set this variable, every AWS command you run in that terminal window will use the prod-user credentials automatically.
⚠️ Always Verify: Before running a destructive command (like deleting a database), verify who you are:
aws sts get-caller-identityThis will return the Account ID and ARN, confirming exactly which profile is active.
Advanced: AWS SSO / Identity Center (Optional but Recommended)
While Access Keys (the ID and Secret combo) are simple to use, they pose a security risk because they technically never expire. If you accidentally commit them to GitHub, they are compromised forever until you manually rotate them.
The modern standard for managing access is AWS IAM Identity Center (formerly AWS SSO). Instead of hardcoded keys, this method uses temporary, short-lived tokens linked to your actual user identity (like your corporate email).
How to Configure SSO
Setting this up is surprisingly similar to the standard configuration.
- Run the SSO configuration command:
aws configure sso - The CLI will ask for your SSO Start URL and SSO Region (get these from your AWS Administrator).
- It will pop open your default web browser and ask you to log in.
- Once authenticated, you select the specific AWS Account and Role you want to use.
Why Use It?
- Automatic Rotation: The credentials expire automatically (usually every 8-12 hours). You don’t need to worry about stale keys.
- Easy Refresh: When your session expires, you just run
aws sso login --profile my-sso-profile, click “Allow” in the browser, and you are back in action. No copy-pasting keys required.
Conclusion
Managing multiple AWS environments doesn’t have to be a guessing game. By moving away from a single default profile and embracing Named Profiles, you gain two massive benefits: Security and Speed.
You minimize the risk of deploying production code to a staging server, and you eliminate the friction of constantly swapping out credentials manually.
Summary of Commands:
aws configure --profile <name>: Create a new profile.aws <command> --profile <name>: Run a command as a specific user.export AWS_PROFILE=<name>: Switch your entire terminal session to that user.aws sts get-caller-identity: The “who am I?” check—use it often!
Now, go ahead and clean up your ~/.aws/credentials file. Your future self (and your security team) will thank you.
