.Aws

Configure AWS CLI with the .aws/config File

Learn how to configure AWS CLI profiles, regions, output formats, IAM roles, IAM Identity Center, credentials, environment variables, and troubleshooting in ~/.aws/config.

The AWS Command Line Interface (AWS CLI) uses shared configuration files to remember settings such as regions, output formats, profiles, and role-assumption details. The main user-level configuration file is commonly ~/.aws/config on Linux and macOS, or %UserProfile%\.aws\config on Windows.

This guide explains how to create and manage that file, how it relates to the credentials file, and how AWS CLI resolves settings and credentials.

The .aws Directory

The .aws directory is a per-user directory commonly used by the AWS CLI and compatible SDKs for shared configuration, credentials, cached login data, and related files. It is located inside the current user's home directory.

Config Versus Credentials

The config file stores non-secret CLI behavior and profile settings. The credentials file can store access keys and temporary session credentials. An external credential provider can supply credentials instead of either file.

Long-term access keys and secret access keys normally belong in the credentials file or an external credential provider, not in config. See the related AWS CLI credentials file guide.

Profiles and Section Names

A profile is a named collection of AWS CLI settings and, depending on the credential method, identity configuration. The default profile is used when no other profile is selected. A named profile separates settings for environments such as personal, development, staging, production, or another AWS account.

In the config file, use [default] for the default profile and [profile name] for every named profile:

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

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

Do not omit the profile prefix from a named section in config. The credentials file uses the shorter form, such as [development].

Use a profile explicitly in scripts when the script must not depend on the user's default profile.

Core Configuration Settings

The command-line option is the most direct one-off override. For example, --region eu-west-1 overrides a profile's region for that command. In general, command-line parameters override environment settings, which can override profile values.

Creating and Updating the Config File

Interactive setup

Run aws configure to set up the default profile interactively. The prompts commonly include an access key, secret access key, default Region, and output format. Avoid entering long-term keys when a role, IAM Identity Center, or another temporary credential method is available.

aws configure

Setting individual values

Use aws configure set to update one setting. Include --profile for a named profile:

aws configure set region us-west-2 --profile development
aws configure set output yaml --profile development

Editing the file directly

The file uses INI-style syntax: a section header in square brackets followed by key = value assignments. Keep one setting per line and use the exact profile header rules.

[profile development]
region = us-west-2
output = yaml
cli_pager =
retry_mode = standard
max_attempts = 4

After editing, inspect the result with:

aws configure list
aws configure list --profile development
aws configure list-profiles

aws configure list shows effective configuration sources, while list-profiles shows profiles discovered by the CLI.

Credentials and the Provider Chain

The AWS CLI uses a credential provider chain: an ordered process that checks multiple possible sources for usable credentials. The exact behavior can vary by CLI version and execution environment, but common sources include:

Prefer temporary credentials, IAM roles, or IAM Identity Center over static keys. Never commit credentials to source control or place them in documentation, shell history, or broadly shared machines.

Assuming an IAM Role from a Profile

An IAM role is an AWS identity with permissions that can be assumed to obtain temporary credentials. A cross-account profile commonly uses a source profile for the initial identity and a target role for access to another account.

[profile engineering-admin]
role_arn = arn:aws:iam::123456789012:role/EngineeringAdmin
source_profile = development
role_session_name = cli-engineering-session
region = us-east-1

• source_profile identifies the profile that supplies the initial credentials.
• role_arn is the Amazon Resource Name that identifies the target role.
• role_session_name labels the temporary role session for auditing.
• external_id supplies a required third-party or confused-deputy protection value when the trust policy requires one.
• duration_seconds requests the session duration, subject to the role and service limits.
• mfa_serial identifies the MFA device when the role requires multi-factor authentication.

The source identity must be allowed to call sts:AssumeRole, and the target role's trust policy must allow that source principal. An access-denied error can result from either side.

IAM Identity Center Profiles

AWS IAM Identity Center provides workforce sign-in and temporary access to assigned AWS accounts and roles. Configure it interactively with:

aws configure sso

Modern configurations commonly separate reusable sign-in information into an sso-session section and account-specific access into a profile:

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

[profile company-readonly]
sso_session = company
sso_account_id = 123456789012
sso_role_name = ReadOnlyAccess
region = us-east-1

The session describes the IAM Identity Center portal and sign-in configuration. The profile references that session and selects an account and role assigned through the portal. Authenticate before use:

aws sso login --profile company-readonly

The CLI stores a local cached token and uses it until it expires or must be refreshed. An unattended job should not depend on an interactive login; use an appropriate workload role or automation credential provider instead.

Environment Variables and Precedence

• AWS_PROFILE selects a profile for the current process.
• AWS_DEFAULT_REGION supplies a default Region.
• AWS_REGION supplies a Region in environments and tools that recognize it.
• AWS_CONFIG_FILE changes the shared config file path.
• AWS_SHARED_CREDENTIALS_FILE changes the shared credentials file path.
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN provide environment credentials. Session credentials require all relevant parts, including the session token.

Conceptually, command-line parameters override environment settings, and environment settings can override profile defaults. Credential resolution still follows the provider chain, so an environment credential, workload role, or external process may supply identity instead of the profile's credentials file.

Custom file paths are useful for isolated shells, tests, and automation:

export AWS_CONFIG_FILE="$PWD/test-config"
export AWS_SHARED_CREDENTIALS_FILE="$PWD/test-credentials"
aws configure list

On Windows PowerShell, equivalent environment assignment uses $env:AWS_CONFIG_FILE = "C:\path\to\config".

Advanced Profile Settings

External credential processes

credential_process runs an external program that returns credentials in the format expected by AWS tooling. Protect the helper and its output, and ensure the command cannot be replaced by an untrusted user.

[profile external-auth]
credential_process = /usr/local/bin/credential-helper --profile external-auth
region = eu-west-1

Web identity

A web identity token is a federated identity token used with a role to request temporary AWS credentials. This is common in containerized or orchestrated workloads:

[profile workload]
role_arn = arn:aws:iam::123456789012:role/WorkloadRole
web_identity_token_file = /var/run/secrets/token
region = us-east-1

source_profile and credential_source

source_profile points to another named profile for initial credentials. credential_source tells the CLI to obtain initial credentials from a supported execution environment instead, such as an attached instance role, an ECS container role, or the environment. Use the approach that matches where the initial identity is provided; do not combine incompatible source methods casually.

Endpoints, CA bundles, and proxies

endpoint_url can direct requests to a controlled custom endpoint. Service-specific endpoint configuration is useful when only one service needs a special address. Use custom endpoints only when required and verify them carefully.

Corporate network setups may also require a custom CA bundle so TLS certificates can be verified, or proxy-related configuration supplied through supported CLI or operating-system settings. A missing corporate CA certificate often causes TLS verification errors; disabling certificate verification is not a safe general solution.

Using Profiles in Commands and SDKs

# Use the default profile
aws s3 ls

# Select a named profile for one command
aws s3 ls --profile development

# Select a profile for the current shell
export AWS_PROFILE=development
aws sts get-caller-identity

Many AWS SDKs can read the shared config and credentials files when shared configuration loading is enabled or supported by that SDK. Check the SDK's documented configuration behavior before assuming that every CLI setting is recognized. In scripts, select a profile explicitly, avoid relying on interactive SSO login, and ensure temporary credentials can refresh without human input.

Security and Operational Practices

• Use least-privilege IAM permissions.
• Use separate profiles for separate accounts and environments.
• Prefer IAM Identity Center, IAM roles, or temporary credentials over static access keys.
• Restrict local file access. On Unix-like systems, protect credential files with permissions such as chmod 600 ~/.aws/credentials where appropriate.
• Do not commit config or credentials files containing secrets to source control.
• Do not paste secrets into tickets, documentation, shell history, or shared logs.
• Use clear names such as company-dev, company-prod-readonly, and company-security.
• Periodically remove unused profiles, expired keys, cached sessions, and obsolete role references.

Validation and Troubleshooting

Always verify the identity before making changes:

aws sts get-caller-identity
aws sts get-caller-identity --profile development
aws configure list
aws configure list-profiles

The --debug option can reveal profile resolution, endpoint selection, and authentication flow:

aws sts get-caller-identity --profile development --debug

Practical Configuration Patterns

Default region and output

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

Named development profile

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

Separate static credentials from settings

# ~/.aws/config
[profile development]
region = us-west-2

# ~/.aws/credentials
[development]
aws_access_key_id = EXAMPLEACCESSKEY
aws_secret_access_key = EXAMPLESECRETKEY

The values above are placeholders, not usable credentials. In real environments, prefer a temporary or role-based source.

Exam-Relevant Notes

• [default] names the default config profile; named config profiles use [profile name].
• The config file normally stores behavior and profile settings; the credentials file can store access keys.
• --profile selects one command's profile, while AWS_PROFILE affects the process environment.
• source_profile uses another profile's credentials for role assumption; credential_source obtains credentials from the execution environment.
• Role assumption requires permission for the source identity and a trusting target role.
• IAM Identity Center profiles require an SSO login and use temporary credentials.
• aws sts get-caller-identity is the quickest way to confirm the active AWS account and identity.