@Fs

AWS CLI Config File: Profiles, Regions, Output, and Role Settings

Learn how to configure ~/.aws/config with AWS CLI profiles, Regions, output formats, role assumption, IAM Identity Center, credential sources, and troubleshooting.

What the AWS CLI config file does

The AWS CLI uses a shared configuration file to store non-secret command-line settings. These settings can include an AWS Region, output format, profile relationships, IAM role-assumption options, retry behavior, and endpoint preferences.

On Unix-like systems, the default path is ~/.aws/config. On Windows, the equivalent is typically %USERPROFILE%\.aws\config.

The config file is different from the companion credentials file, which commonly stores static access keys and named credential profiles. A profile can use settings from both files, or obtain credentials from another provider without storing credentials locally.

Values can come from several sources. In general, a command-line option such as --region or --output overrides environment and file settings. Environment variables such as AWS_REGION, AWS_DEFAULT_REGION, and AWS_PROFILE commonly override corresponding file-based choices. The exact provider order can vary by setting, so use aws configure list to inspect the resolved source.

INI syntax and profile sections

The config file uses INI-style sections. A section name is enclosed in brackets, and each setting uses a key, an equals sign, and a value.

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

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

Default profile: The special [default] section is used when no explicit profile is selected.

Named profile: Every non-default profile in the config file uses the [profile profile-name] form. For example, the profile named development is written as [profile development].

This differs from the credentials file. The same profile is written as [development] in ~/.aws/credentials. Omitting the profile prefix in the config file can cause settings to be ignored.

Regions and output formats

An AWS Region is a geographic area where many AWS services and resources are scoped. Configure a Region when a command or service requires one.

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

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

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

The profile-specific values apply when that profile is active. Common output formats are json, yaml, yaml-stream, text, and table.

Override a configured value for one command without editing the file:

aws s3 ls --profile development --region eu-west-1 --output table

Creating and selecting profiles

aws configure interactively creates or updates the default profile. To work with a named profile, provide --profile.

aws configure
aws configure --profile development

For non-secret settings, aws configure set writes directly to the selected profile:

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

Select a profile for one command with --profile:

aws sts get-caller-identity --profile development

Alternatively, set AWS_PROFILE in the current shell:

AWS_PROFILE=development aws ec2 describe-regions

When neither --profile nor AWS_PROFILE selects a profile, the CLI uses [default].

Use descriptive names such as development, production-readonly, or audit-account-a to separate accounts, environments, and roles.

Credential sources and profile relationships

A profile does not have to contain credentials. The CLI can obtain credentials from the environment, the credentials file, a credential process, IAM Identity Center, or instance and container metadata.

source_profile names another local profile whose credentials are used to obtain credentials for the current profile. credential_source instead tells the CLI to use a runtime provider. Supported values include Environment, Ec2InstanceMetadata, and EcsContainer.

IAM role-assumption profiles

An IAM role-assumption profile uses initial credentials to obtain temporary credentials for a target IAM role. The target role is identified by role_arn.

[profile engineering-readonly]
role_arn = arn:aws:iam::123456789012:role/EngineeringReadOnly
source_profile = developer
role_session_name = cli-engineering-session
region = us-east-1

source_profile references a local base profile. For workloads that receive credentials through the environment, use credential_source instead:

[profile deployment-role]
role_arn = arn:aws:iam::123456789012:role/DeploymentRole
credential_source = Environment
region = us-east-1

role_session_name labels the temporary session. A descriptive value can improve CloudTrail and other audit records. Some roles also require external_id or mfa_serial:

[profile vendor-access]
role_arn = arn:aws:iam::123456789012:role/VendorAccess
source_profile = vendor-base
role_session_name = approved-vendor-session
external_id = approved-external-id
mfa_serial = arn:aws:iam::123456789012:mfa/operator

The source identity must be allowed to call sts:AssumeRole, and the target role trust policy must trust that identity. Role chaining means assuming a role using credentials that were themselves obtained by assuming another role. Chained sessions have stricter duration limitations, so avoid unnecessary chains and design the trust path deliberately.

Select an assume-role profile like any other profile:

aws sts get-caller-identity --profile engineering-readonly

IAM Identity Center profiles

IAM Identity Center, previously commonly called AWS SSO, provides browser-based workforce sign-in and temporary AWS credentials. Modern configuration separates reusable sign-in data into an sso-session section. A profile references that session with sso_session.

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

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

sso_start_url identifies the organization's IAM Identity Center portal, sso_region identifies the sign-in service Region, and sso_account_id and sso_role_name select the AWS account and role where applicable.

Sign in before using the profile:

aws sso login --profile company-admin
aws sts get-caller-identity --profile company-admin

The CLI caches temporary sign-in tokens locally. They expire and should not be manually copied or treated as static access keys.

Advanced configuration settings

Web identity configuration commonly combines role_arn with web_identity_token_file:

[profile workload]
role_arn = arn:aws:iam::123456789012:role/WorkloadRole
web_identity_token_file = /path/to/approved/token
region = us-east-1

Use endpoint_url only when an approved environment requires a local emulator, private endpoint, or other nonstandard service endpoint. A custom endpoint can change where commands send data. When TLS uses an organizational certificate authority, configure ca_bundle rather than disabling certificate verification.

Inspecting and validating configuration

List profiles recognized by the CLI:

aws configure list-profiles

Inspect resolved settings and their sources for the default profile:

aws configure list

Inspect a named profile:

aws configure list --profile development

Use the harmless identity operation sts get-caller-identity to verify the active account and principal:

aws sts get-caller-identity --profile development

Use --debug carefully when diagnosing provider selection, profile loading, region selection, or endpoint resolution:

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

Debug output can reveal paths, provider behavior, and request details. Do not share it without reviewing and removing sensitive information.

Troubleshooting common problems

A Region is required

• Check the intended profile with aws configure list --profile profile-name.
• Check whether AWS_PROFILE selects a different profile.
• Run the command with an explicit --region to confirm the cause.
• Set region in the intended profile or use an approved environment override.

Credentials cannot be located

• Verify the selected profile and its credential source.
• Check that a source_profile exists and is spelled correctly.
• For credential_source = Environment, confirm that the runtime injected usable credentials.
• For IAM Identity Center, run aws sso login --profile profile-name.
• Confirm the result with aws sts get-caller-identity --profile profile-name.

Role assumption is denied

• Identify the source principal with sts get-caller-identity.
• Verify that it has sts:AssumeRole permission.
• Review the target role trust policy.
• Check role_arn, source_profile, external_id, and mfa_serial.

A named config profile is ignored

• Use [profile name] in the config file.
• Use [name] in the credentials file.
• Run aws configure list-profiles to see which names the CLI recognizes.

Unexpected credentials or settings are used

• Run aws configure list and inspect the source of each resolved value.
• Check AWS_PROFILE, AWS_REGION, AWS_DEFAULT_REGION, and other AWS environment variables.
• Check shell startup files and CI configuration for injected values.
• Use --profile explicitly and verify the account with sts get-caller-identity.

Certificate validation fails for a custom endpoint

• Verify the endpoint setting and network path.
• Ask the endpoint operator to confirm the certificate chain.
• Configure an authorized organizational ca_bundle when required.
• Do not disable certificate verification as a routine workaround.

Security and operational practices

• Keep long-term access keys out of the config file and avoid committing either ~/.aws/config or ~/.aws/credentials to source control.
• Prefer IAM roles, IAM Identity Center, temporary credentials, or workload identity over static access keys.
• Restrict permissions on AWS configuration and credential files. On Unix-like systems, review ownership and use restrictive permissions such as chmod 600 ~/.aws/credentials where appropriate.
• Use descriptive profile names and separate production access from development and testing access.
• Do not share profile files casually. Even configuration-only files can disclose account IDs, role names, internal endpoints, or local credential-provider commands.
• Review external credential-process commands before enabling them, because the command runs locally and can access its execution environment.