How to switch AWS CLI profiles

A shell that still points at yesterday's AWS CLI profile can inspect or change resources in the wrong AWS account. Switching profiles with an explicit selector makes the account, role, or IAM Identity Center session visible before account-sensitive commands run.

A named profile is a saved entry under ~/.aws/config, ~/.aws/credentials, or both. Use --profile when one command should use a named profile, and use AWS_PROFILE when a shell session or script should keep using that profile until the variable is cleared.

The command-line profile option overrides an exported profile for that one request. Raw credential variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN can still override the credentials behind a named profile, so check aws configure list before deployments, data copies, or permission changes.

1. List the saved profile names.

   $ aws configure list-profiles
   default
   engineering
   production

   The target name must already exist in the shared config or credentials files before it can be selected.

2. Use --profile production when only one command should use the named profile.

   $ aws configure list --profile production
   NAME       : VALUE                    : TYPE             : LOCATION
   profile    : production               : manual           : --profile
   access_key : ****************DUCE     : shared-credentials-file :
   secret_key : ****************EKEY     : shared-credentials-file :
   region     : eu-west-1                : config-file      : ~/.aws/config

   The profile row should show manual from --profile, which means this command is not falling back to [default] or an exported shell profile.

3. Use AWS_PROFILE as a one-command environment prefix when the command expects its profile from the environment.

   $ AWS_PROFILE=production aws configure list
   NAME       : VALUE                    : TYPE             : LOCATION
   profile    : production               : env              : ['AWS_PROFILE', 'AWS_DEFAULT_PROFILE']
   access_key : ****************DUCE     : shared-credentials-file :
   secret_key : ****************EKEY     : shared-credentials-file :
   region     : eu-west-1                : config-file      : ~/.aws/config

   A one-command prefix disappears when the command exits. Use export AWS_PROFILE=production only when following commands in the same shell should keep that profile.

4. Clear raw credential variables before making a profile the shell default.

   $ unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

   If aws configure list shows env for access_key or secret_key, those raw credentials are winning over the file-backed credentials for the selected profile.

5. Export AWS_PROFILE when several commands in the same shell should use the profile.

   $ export AWS_PROFILE=production

6. Confirm that the shell now resolves the intended profile.

   $ aws configure list
   NAME       : VALUE                    : TYPE             : LOCATION
   profile    : production               : env              : ['AWS_PROFILE', 'AWS_DEFAULT_PROFILE']
   access_key : ****************DUCE     : shared-credentials-file :
   secret_key : ****************EKEY     : shared-credentials-file :
   region     : eu-west-1                : config-file      : ~/.aws/config

   Run a caller identity check before commands that can change live resources, then compare the returned account or Arn with the intended environment.
   Related: How to check the current caller identity in AWS CLI

7. Override the exported profile for a single command when another profile is needed.

   $ aws configure list --profile engineering
   NAME       : VALUE                    : TYPE             : LOCATION
   profile    : engineering              : manual           : --profile
   access_key : ****************NEER     : shared-credentials-file :
   secret_key : ****************EKEY     : shared-credentials-file :
   region     : us-west-2                : config-file      : ~/.aws/config

   The profile row returns to manual because --profile engineering has higher precedence than the exported AWS_PROFILE=production value for this command.

8. Clear the shell-level profile selection when the session should stop using it.

   $ unset AWS_PROFILE AWS_DEFAULT_PROFILE

   Clear AWS_DEFAULT_PROFILE too if shell startup files or wrapper scripts set it.

9. Confirm that the shell has fallen back to the expected default profile or shared-file settings.

   $ aws configure list
   NAME       : VALUE                    : TYPE             : LOCATION
   profile    : <not set>                : None             : None
   access_key : ****************MPLE     : shared-credentials-file :
   secret_key : ****************EKEY     : shared-credentials-file :
   region     : us-east-1                : config-file      : ~/.aws/config

   If the profile row still shows env, another exported variable or command wrapper is still overriding the session.