AWS CLI Setup & Configuration

Overview

The AWS CLI is the unified command-line tool for interacting with every AWS service. This reference covers installation, credential management, named profiles, SSO-based authentication, and essential configuration patterns.

Installation

Linux

The official installer is the recommended way to get AWS CLI v2 on Linux — distro packages often lag behind releases or still ship the deprecated v1. It installs the binary to /usr/local/bin/aws and can be updated by re-running the same script.

# Download and install
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Verify
aws --version

macOS

Homebrew is the simplest option on macOS and stays current with each AWS release. Alternatively, the official .pkg installer provides a signed, controlled install if you prefer not to use Homebrew.

brew install awscli

# Or the official installer
curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" -o "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

Windows

Run the MSI installer — it configures PATH automatically so the aws command works in a new terminal. After installing, open a fresh PowerShell window and confirm with aws --version.

msiexec.exe /i https://awscli.amazonaws.com/AWSCLIV2.msi

Configuration files

The AWS CLI reads all of its settings from two plain-text files under ~/.aws. Credentials live separately from non-secret profile settings, so you can share ~/.aws/config (e.g. via dotfiles) without leaking secrets.

~/.aws/config          # Profiles and non-credential settings
~/.aws/credentials     # Access keys and secret keys

Minimal config

A working ~/.aws/config only needs a default region and output format; ~/.aws/credentials holds the matching access keys. The CLI merges the two files by matching section names, so [default] in one pairs with [default] in the other.

# ~/.aws/config
[default]
region = us-east-2
output = json

# ~/.aws/credentials
[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

Named profiles

Multiple profiles let you switch between accounts, roles, and regions without reconfiguring.

# ~/.aws/config
[default]
region = us-east-2
output = json

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

[profile staging]
region = eu-west-1
output = table

# ~/.aws/credentials
[default]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

[production]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

[staging]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

Using profiles

Profiles are selected per command, per shell session, or per command block. The AWS_PROFILE environment variable form is especially common in CI/CD, where each job targets a different account.

# Use a specific profile for a single command
aws s3 ls --profile production

# Default to this profile for the rest of the shell session
export AWS_PROFILE=staging
aws s3 ls

# Apply a profile to a single command's environment
AWS_PROFILE=production terraform plan

IAM Identity Center (SSO)

AWS SSO (now IAM Identity Center) is the recommended authentication method — no long-lived access keys needed.

Configure a profile

aws configure sso walks through SSO profile creation interactively. It opens a browser for authentication, then records the account, role, region, and output format you pick.

aws configure sso

# Interactive prompts:
# SSO session name: my-sso
# SSO start URL: https://d-abc123.awsapps.com/start
# SSO region: us-east-2
# SSO registration scopes: sso:account:access
#
# The browser opens for authentication. Then:
# Select account, role, default region, output format.

This writes to ~/.aws/config:

[profile admin]
sso_session = my-sso
sso_account_id = 123456789012
sso_role_name = AdministratorAccess
region = us-east-2
output = json

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

Authentication happens on demand: running aws sso login for a profile opens the browser and caches temporary credentials on disk. Re-run it when a token expires or your role changes.

aws sso login --profile admin
# Opens browser for authentication
# Credentials cached in ~/.aws/sso/cache/

SSO tokens expire after a configurable period (default 8 hours). Re-run aws sso login to refresh.

Multiple accounts and roles

A single sso-session can back many profiles, each mapping to a different account and role combination. This keeps sign-in to one browser flow while letting you scope each command to the right permission set.

[profile dev-admin]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = AdministratorAccess

[profile dev-readonly]
sso_session = my-sso
sso_account_id = 111111111111
sso_role_name = ReadOnlyAccess

[profile prod-admin]
sso_session = my-sso
sso_account_id = 222222222222
sso_role_name = AdministratorAccess

Switch with --profile or AWS_PROFILE.

IAM role assumption

Assume a role from an existing profile (cross-account access):

# ~/.aws/config
[profile cross-account]
role_arn = arn:aws:iam::222222222222:role/ReadOnlyAccess
source_profile = default
region = us-east-2

No credentials needed in the file — the CLI calls sts:AssumeRole using source_profile's credentials and caches temporary tokens.

To require MFA:

[profile cross-account-mfa]
role_arn = arn:aws:iam::222222222222:role/AdminAccess
source_profile = default
mfa_serial = arn:aws:iam::111111111111:mfa/admin-user
region = us-east-2

Environment variables

Environment variables override the config files, making them ideal for CI/CD, containers, and ephemeral shells. They take effect for every AWS CLI and SDK process that inherits them.

export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...           # required for temporary credentials

export AWS_DEFAULT_REGION=us-east-2    # or AWS_REGION
export AWS_PROFILE=production
export AWS_CONFIG_FILE=/custom/path/config
export AWS_SHARED_CREDENTIALS_FILE=/custom/path/credentials

# Instance metadata (on EC2)
export AWS_EC2_METADATA_DISABLED=true  # disable IMDS

Precedence: CLI parameters → environment variables → ~/.aws/credentials → ~/.aws/config → instance profile (on EC2) → container credentials (on ECS).

Configuration settings

Beyond the region and output format, ~/.aws/config controls paging, retries, timestamp formatting, and S3 transfer behavior. The s3 block tunes how large uploads and downloads are split and how aggressively they run in parallel.

# ~/.aws/config
[default]
region = us-east-2
output = json
cli_pager = ""                          # disable pager
cli_auto_prompt = on                    # v2 auto-complete
cli_timestamp_format = iso8601

# Retry configuration
max_attempts = 5
retry_mode = adaptive

# S3-specific
s3 =
    max_concurrent_requests = 20
    max_queue_size = 10000
    multipart_threshold = 64MB
    multipart_chunksize = 16MB
    use_accelerate_endpoint = false
    addressing_style = path

Common commands

Account and identity

These commands answer the first question of any access issue: who am I authenticated as, and what did the CLI pick up from my config? aws configure list shows the effective, merged settings for a profile.

# Verify the current caller's account, ARN, and user ID
aws sts get-caller-identity
aws sts get-caller-identity --profile production

# List all configured profiles
aws configure list-profiles

# View effective configuration
aws configure list
aws configure list --profile production

Configuration management

These commands read and write the config files without hand-editing them. aws configure set is script-friendly, letting automation set a region or access key for a specific profile in one line.

# Interactive setup
aws configure

# Set individual values
aws configure set region us-west-2
aws configure set region us-west-2 --profile staging
aws configure set aws_access_key_id AKIA... --profile production

# Get a value
aws configure get region
aws configure get region --profile production

# Import/export specific profiles
aws configure import --csv file://credentials.csv

Credential validation

When credentials stop working, these commands confirm whether they are valid, what permissions they actually have, and what went wrong. sts decode-authorization-message translates opaque AccessDenied errors into readable policy details.

# Test credentials by calling an API
aws sts get-caller-identity
aws s3 ls                     # requires S3 permissions

# Decode an authorization error message
aws sts decode-authorization-message \
  --encoded-message <message>

# Check if MFA is enabled on a user
aws iam list-mfa-devices --user-name alice

CLI v2 features

Auto-prompt

The CLI v2 auto-prompt turns each invocation into an interactive form: it lists available parameters and offers autocompletion for things like resource IDs and --filters. It is a great discovery aid for unfamiliar commands.

aws configure set cli_auto_prompt on

# Then run and the CLI shows interactive prompts
aws ec2 describe-instances  # shows available --filters interactively

Wizard

Wizards provide guided, step-by-step setup for common tasks. They are handy for one-off configurations or for learning which parameters a service actually requires.

aws configure wizard         # guided setup
aws dynamodb wizard          # guided table creation

Binary parameter shorthand

CLI v2 accepts JSON values inline on the command line instead of pointing at file:// documents. Wrap the payload in single quotes so the shell does not interpret the braces and quotes.

# Inline JSON (v1: file:// only, v2: inline supported)
aws dynamodb put-item \
  --table-name Users \
  --item '{"id": {"S": "abc"}, "name": {"S": "Alice"}}'

Docker usage

The official amazon/aws-cli image runs the CLI inside a container, so no local installation is needed. Mount ~/.aws read-only so the container picks up your existing profiles and credentials.

# Mount ~/.aws into the container
docker run --rm \
  -v ~/.aws:/root/.aws:ro \
  -e AWS_PROFILE=production \
  amazon/aws-cli s3 ls

# Or pass env vars directly
docker run --rm \
  -e AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY \
  -e AWS_DEFAULT_REGION \
  amazon/aws-cli s3 ls

Troubleshooting

When a command fails, these steps isolate the cause: debug logging reveals the exact credential chain and request details, while aws configure list verifies which profile and settings are actually in effect.

# Enable debug output
aws s3 ls --debug

# Check credential chain resolution
aws sts get-caller-identity --debug 2>&1 | grep -E "credentials|config"

# Verify a specific profile
aws configure list --profile production

# Clear SSO cache (force re-authentication)
rm -rf ~/.aws/sso/cache/

# Test connectivity
aws ec2 describe-regions --region us-east-1

# Check CLI version
aws --version

Overview​

Installation​

Linux​

macOS​

Windows​

Configuration files​

Minimal config​

Named profiles​

Using profiles​

IAM Identity Center (SSO)​

Configure a profile​

Login​

Multiple accounts and roles​

IAM role assumption​

Environment variables​

Configuration settings​

Common commands​

Account and identity​

Configuration management​

Credential validation​

CLI v2 features​

Auto-prompt​

Wizard​

Binary parameter shorthand​

Docker usage​

Troubleshooting​

See also​