Root

AWS CLI Configuration File (~/.aws/config)

Learn how to manage ~/.aws/config: profiles, regions, output formats, IAM Identity Center, role assumption, endpoints, precedence, and safe AWS CLI practices.

What the AWS CLI configuration file does

The AWS CLI configuration file stores non-secret settings that control how the command-line client behaves. Its standard location is ~/.aws/config on Linux and macOS. On Windows, the equivalent path is %UserProfile%\.aws\config.

AWS CLI settings are grouped into profiles. A profile is a named collection of settings such as a Region, output format, endpoint, or authentication method. The default profile is used when no other profile is selected.

The configuration file normally contains preferences and authentication references, not secret access keys. Static access keys are conventionally stored in ~/.aws/credentials. The two files can work together: a profile in the config file can use credentials with the same profile name from the credentials file.

File locations and discovery

The tilde character, ~, represents the current user's home directory on Unix-like systems. The CLI looks in that user's .aws directory unless an alternate configuration path is selected.

Use AWS_CONFIG_FILE when automation needs an isolated configuration file:

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

On PowerShell, the equivalent is:

$env:AWS_CONFIG_FILE = "$PWD\test-config"
aws configure list

Make sure the file is owned by the intended user and is readable only by users who need it. A configuration-only file may not contain secrets, but restrictive permissions reduce accidental disclosure and help prevent unauthorized changes. Credential-bearing files should have especially restrictive permissions.

INI structure and profile names

The file uses an INI-like format. A section is enclosed in square brackets. Each setting has a key, an equals sign, and a value. Comments commonly begin with # or ;. Whitespace around keys and values is generally ignored.

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

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

The section named [default] defines the default profile. Named profiles use the convention [profile name] in the config file. For example, [profile development] defines a profile selected with the name development.

Every command has a selected profile. The CLI reads settings from that profile and combines them with applicable environment variables, credentials providers, and built-in defaults.

Profile names must be spelled consistently. A section called [development] is not the normal named-profile form in the config file; use [profile development]. The credentials file uses a different section convention: named credential sections are written as [development], without the profile prefix.

Basic settings: Region and output

A Region is an AWS geographic deployment area. The region setting tells the CLI where to send requests for regional services. It does not automatically change the account or identity being used.

The output setting controls how command responses are rendered. Common values are json, yaml, yaml-stream, text, and table.

The interactive command aws configure creates or updates the default profile. It can ask for access-key values, a secret key, Region, and output format. To modify a named profile, include --profile:

aws configure
aws configure --profile development
aws configure set region us-west-2 --profile development
aws configure get region --profile development

Inspect the values and their sources with:

aws configure list
aws configure list --profile development

Named profiles and profile selection

Named profiles are useful when one workstation accesses several AWS accounts, environments, permission sets, or roles. Keeping development, testing, and production profiles separate makes the intended context explicit.

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

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

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

Select a profile for one command with the global command option:

aws sts get-caller-identity --profile development

Select a profile for an entire shell process with AWS_PROFILE:

export AWS_PROFILE=development
aws sts get-caller-identity

For profile selection, an explicit --profile option takes priority over AWS_PROFILE. If neither is present, the CLI uses default.

Exact precedence varies by setting. For example, environment credentials can be selected before shared-profile credentials, while a role profile can deliberately direct the CLI to a source profile. When behavior matters, inspect the resolved configuration and credentials source rather than relying on memory.

Config file versus credentials file

The conventional division is:

• ~/.aws/config: Regions, output formats, role settings, IAM Identity Center settings, endpoint settings, retry behavior, paging, and other CLI preferences.
• ~/.aws/credentials: Static access key ID, secret access key, and sometimes session token values for profiles that use static credentials.

A profile can combine settings from both files. For example, [profile development] in the config file can use [development] in the credentials file, along with the config file's Region and output format.

Static credentials are simple but have limitations: they are long-lived unless rotated, can be copied accidentally, and are difficult to control once exposed. Prefer temporary credentials from IAM Identity Center, assumed roles, workload identity, or another supported provider.

A profile does not necessarily need credentials in the credentials file. It may obtain them through credential_process, IAM Identity Center, a role source, environment variables, container credentials, or instance metadata.

Authentication profile patterns

The AWS CLI uses a credential provider chain: an ordered set of possible credential sources. Depending on the environment and profile, sources can include command-related settings, environment credentials, shared files, an external process, IAM Identity Center, assumed roles, container credentials, and instance metadata. A profile's role or SSO settings can cause the CLI to obtain temporary credentials instead of reading static keys directly.

External credential processes

The credential_process setting tells the CLI to run an external program that returns credentials in the AWS process-credential format. This is useful when an organization uses a credential broker or another approved authentication tool.

[profile enterprise]
region = us-east-1
credential_process = /path/to/approved-credential-helper

Use an approved, secured executable path. Do not place secret output directly in the config file, shell history, source control, or diagnostic logs.

IAM Identity Center profiles

IAM Identity Center provides workforce sign-in and short-lived CLI credentials. Modern configurations can define a reusable sso-session section and reference it from one or more profiles.

[sso-session company]
sso_start_url = YOUR_IAM_IDENTITY_CENTER_START_URL
sso_region = us-east-1
sso_registration_scopes = sso:account:access

[profile workforce]
sso_session = company
sso_account_id = 123456789012
sso_role_name = ReadOnly
region = us-east-1
output = json

The important settings are:

• sso_start_url: The organization's IAM Identity Center start address.
• sso_region: The Region hosting the IAM Identity Center instance.
• sso_account_id: The target AWS account for the profile.
• sso_role_name: The permission set or role exposed to the user.
• sso_session: The reusable session definition referenced by the profile.

Authenticate or refresh the cached session with:

aws sso login --profile workforce
aws sts get-caller-identity --profile workforce

Several profiles can reference one sso-session while selecting different account and role combinations:

[profile development-sso]
sso_session = company
sso_account_id = 111111111111
sso_role_name = Developer
region = us-west-2

[profile production-sso]
sso_session = company
sso_account_id = 222222222222
sso_role_name = ReadOnly
region = us-east-1

If login fails, check the session name, start address, SSO Region, account ID, role name, and the user's account and permission-set assignments.

Role-based profiles

A role-based profile obtains temporary credentials by assuming an IAM role. The target role is identified by role_arn. The source identity can come from another profile or from the runtime environment.

[profile base]
region = us-east-1

[profile production-readonly]
role_arn = arn:aws:iam::123456789012:role/ReadOnly
source_profile = base
region = us-east-1
role_session_name = cli-session

Here, the CLI first resolves base, then calls AWS Security Token Service to assume the role in the target account. The source identity needs permission to call sts:AssumeRole, and the target role's trust policy must trust that identity.

Useful role settings include:

• role_arn: ARN of the role to assume.
• source_profile: Profile supplying credentials for the assume-role operation.
• role_session_name: A human-readable name for the temporary session.
• duration_seconds: Requested lifetime, subject to role and session limits.
• external_id: An additional value required by some cross-account trust policies.

A role can use a runtime credential source instead of a named source profile:

[profile workload-role]
role_arn = arn:aws:iam::123456789012:role/WorkloadRole
credential_source = Ec2InstanceMetadata
region = us-east-1

Common credential-source concepts include environment credentials, EC2 instance metadata, and ECS container credentials. Web identity configurations are commonly used by federated or containerized workloads and obtain a role session from a web-identity token supplied by the runtime.

Multi-hop role relationships are possible, but every hop adds latency, expiration constraints, trust-policy dependencies, and troubleshooting complexity. Keep the chain short. MFA may be required by the role trust policy or organization policy; configure the appropriate MFA behavior and be prepared for an interactive prompt or a credential helper.

Endpoint and service settings

An endpoint_url replaces a standard AWS service endpoint with a custom endpoint. It can be useful for private connectivity, local testing, or an AWS-compatible API implementation.

[profile local-test]
region = us-east-1
endpoint_url = http://localhost:4566
output = json

Some CLI configurations also support service-specific endpoint overrides, allowing one service to use a custom endpoint while other services continue using normal endpoints. Keep these overrides in an explicitly named test or private-connectivity profile.

Useful CLI behavior settings

• cli_pager: Selects the pager used for output. Set it to an empty value to disable paging.
• cli_auto_prompt: Controls automatic prompting for missing or suggested command parameters.
• cli_binary_format: Controls how binary parameters are interpreted, such as raw bytes versus base64 encoding.
• retry_mode: Selects the retry strategy supported by the CLI version.
• max_attempts: Limits the number of attempts made by retry logic.
• ca_bundle: Points to a custom certificate-authority bundle for TLS verification.
• tcp_keepalive: Controls TCP keepalive behavior where supported.
• request_checksum_calculation and response_checksum_validation: Control checksum handling for services and operations where these options apply.

[profile automation]
region = us-east-1
output = json
cli_pager =
cli_auto_prompt = off
retry_mode = standard
max_attempts = 3

Disabling the pager is especially useful in scripts and CI jobs because output is emitted directly rather than opened interactively.

Inspecting configuration and precedence

Use the CLI's inspection commands before changing files manually:

aws configure list
aws configure list --profile development
aws configure get region --profile development
aws configure get output --profile development

aws configure list helps show the active profile's Region, credential source, and related values. Values may be masked when they are sensitive. aws configure get reads a particular configuration key.

When investigating a surprising result, check:

1. The explicit command options, especially --profile, --region, and endpoint options.
2. Environment variables such as AWS_PROFILE, AWS_CONFIG_FILE, AWS_REGION, credential variables, and endpoint variables.
3. The selected section in the config file and the matching credential section.
4. Role relationships such as source_profile and credential_source.
5. Identity-provider session status and workload metadata availability.

Use --debug carefully when normal inspection is insufficient:

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

Debug output can reveal file paths, profile decisions, endpoints, request details, and authentication flow. Redirect it to a protected location if necessary, and review it before sharing. Never publish logs that contain access keys, session tokens, authorization headers, or other sensitive values.

Safe management practices

• Keep secret keys out of ~/.aws/config whenever possible.
• Restrict permissions on ~/.aws/credentials and any file containing tokens or generated credentials.
• Do not commit ~/.aws files, copied profiles, or credential-process output to source control.
• Prefer temporary credentials, IAM Identity Center, assumed roles, or workload identity over permanent access keys.
• Use separate profiles for development, testing, and production.
• Review role_arn, source_profile, and endpoint settings before high-impact operations.
• Use an isolated file through AWS_CONFIG_FILE for automation that must not depend on an operator's personal profiles.

For the complementary file, see AWS CLI credentials.

Troubleshooting common problems

No Region is configured

Likely causes include a missing region in the selected profile, an unintended profile, or a script using another config file. Run aws configure list, check AWS_PROFILE and AWS_CONFIG_FILE, then set a Region or pass --region.

A named profile cannot be found

Check that the config section uses [profile profile-name], that spelling and case match, and that the expected file is being read. Test with aws configure list --profile profile-name.

The CLI uses the wrong AWS account

Run aws sts get-caller-identity with the intended profile. Check AWS_PROFILE, credential-related environment variables, and the role_arn/source_profile relationship.

IAM Identity Center access has expired

Run aws sso login --profile profile-name. Then verify the referenced sso-session, start address, SSO Region, account ID, role name, and permission-set assignment.

Role assumption is denied

Verify the active source identity, its sts:AssumeRole permission, the target role trust policy, and any MFA or external_id requirement.

Requests use an unexpected endpoint

Inspect profile-level endpoint_url settings and endpoint-related environment variables. Confirm that a test profile was not selected accidentally, and use cautious debug output if needed.

Exam-relevant notes

• ~/.aws/config stores shared CLI configuration; ~/.aws/credentials conventionally stores static credentials.
• The default section is [default]; named config profiles use [profile name].
• AWS_PROFILE selects a profile for a process, while AWS_CONFIG_FILE selects an alternate config path.
• An explicit --profile normally overrides AWS_PROFILE.
• role_arn identifies the target role; source_profile identifies the profile that supplies source credentials.
• credential_source obtains source credentials from a runtime source such as instance or container credentials.
• IAM Identity Center profiles use reusable sso-session definitions and are refreshed with aws sso login.
• Always verify the effective identity with aws sts get-caller-identity before sensitive operations.