Navigation

AWS aws getting-started 5 min read

Working with CLI Profiles

Most engineers end up working with more than one AWS account: a personal sandbox, a company dev account, and a production account, for example. A named profile is a saved set of credentials and settings that the AWS CLI (Command Line Interface, the aws command in your terminal) can switch between, so you don’t have to log in and out or copy-paste keys every time. This page shows you how to create profiles, pick which one a command uses, and avoid the single most common (and most dangerous) mistake: running a command against the wrong account.

Where profiles live

The AWS CLI v2 reads two files in your home directory:

File	Path	What it holds
Config	`~/.aws/config`	Region, output format, SSO settings, role definitions
Credentials	`~/.aws/credentials`	Long-lived access keys (key ID + secret)

On Windows these live under %USERPROFILE%\.aws\. The split exists so you can share the non-secret config file (in a team wiki, for example) while keeping credentials private. A profile is just a named block in these files.

A minimal ~/.aws/credentials with two profiles looks like this:

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

[dev]
aws_access_key_id = AKIAI44QH8DHBEXAMPLE
aws_secret_access_key = je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY

And the matching ~/.aws/config:

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

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

Note the naming quirk: in credentials the section is just [dev], but in config it must be [profile dev]. The default profile is the exception — it is written as [default] in both files.

Creating a profile

Console

Profiles are a CLI feature, so there is no console screen for them. The console part is creating the credentials you’ll put in a profile:

Sign in to the AWS Management Console and open IAM (Identity and Access Management, the service that manages users and permissions).
Go to Users, pick your user, then the Security credentials tab.
Under Access keys choose Create access key, select Command Line Interface (CLI), and confirm.
Copy the Access key ID and Secret access key (the secret is shown only once).

CLI

The fastest way is the interactive wizard, which writes both files for you:

aws configure --profile dev

It prompts for four values:

AWS Access Key ID [None]: AKIAI44QH8DHBEXAMPLE
AWS Secret Access Key [None]: je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Default region name [None]: eu-west-1
Default output format [None]: json

When to use long-lived keys: only for automation that can’t use anything better, or quick local experiments. For your own human access, prefer SSO (shown below) — keys that never expire are a security liability if they leak.

Choosing which profile runs

There are two ways to select a profile for a command. They do the same thing; pick whichever fits.

Per-command with --profile:

aws s3 ls --profile dev

For a whole terminal session with the AWS_PROFILE environment variable:

export AWS_PROFILE=dev
aws s3 ls

To confirm which account a profile actually points at before you do anything risky, ask STS (Security Token Service, the service that reports your current identity):

aws sts get-caller-identity --profile dev

Output:

{
    "UserId": "AIDAEXAMPLEUSERID123",
    "Account": "222233334444",
    "Arn": "arn:aws:iam::222233334444:user/jaswinder"
}

The Account field is the 12-digit account ID. Eyeball it before running anything destructive.

Configuring an SSO profile

AWS IAM Identity Center (formerly AWS SSO, Single Sign-On) gives you short-lived credentials that refresh through your browser, so no secret keys ever sit on disk. This is the recommended option for human users in 2026.

aws configure sso --profile work

The wizard asks for your SSO start URL and region, opens a browser to log in, then lets you pick an account and permission set. It writes a block like this to ~/.aws/config:

[profile work]
sso_session = my-org
sso_account_id = 555566667777
sso_role_name = PowerUserAccess
region = us-east-1
output = json

[sso-session my-org]
sso_start_url = https://my-org.awsapps.com/start
sso_region = us-east-1
sso_registration_scopes = sso:account:access

When the session expires, refresh it with aws sso login --profile work. There are no keys to rotate or leak.

A role-assuming profile

A profile can also assume a role in another account — common in multi-account setups where you log in once and “jump” into other accounts. The source_profile says which credentials to start from, and role_arn says which role to assume.

[profile prod]
role_arn = arn:aws:iam::888899990000:role/OrganizationAccountAccessRole
source_profile = work
region = us-east-1

Now aws s3 ls --profile prod uses your work credentials to assume the prod role automatically. The CLI handles the temporary credentials behind the scenes.

The default-profile gotcha

This is the one to burn into memory. When you omit --profile and AWS_PROFILE is not set, the CLI silently uses the default profile. No warning, no prompt.

Warning: If your default profile is production, then a quick aws s3 rb s3://my-bucket you thought was hitting your sandbox just deleted a real bucket. There is no “are you sure”. Engineers have terminated live instances and emptied production buckets this way.

How to protect yourself:

Leave default pointing at a harmless sandbox, or don’t define a default at all — an undefined default makes the CLI error out instead of guessing.
Get in the habit of always passing --profile, even when you think you know the context.
Run aws sts get-caller-identity before any irreversible command.
Show the active profile in your shell prompt (many starship/oh-my-zsh themes do this) so the account is always visible.

Best practices

Prefer SSO (IAM Identity Center) over long-lived access keys for all human access — credentials expire automatically.
Never commit ~/.aws/credentials to git; add it to your global gitignore.
Use role-assuming profiles with source_profile for multi-account access instead of separate keys per account.
Rotate any long-lived access keys regularly and delete keys you no longer use in the IAM console.
Keep default safe (sandbox or undefined) so an omitted --profile can’t hit production.
Verify identity with aws sts get-caller-identity --profile <name> before destructive commands.
There is no cost for using profiles, SSO, or assumed roles — they are free CLI and IAM features.