Temporary Profile Switching in AWS CLI: Version Differences and Practical Implementation

In cloud computing operations and development, AWS CLI serves as a fundamental tool for interacting with Amazon Web Services, where efficient configuration management directly impacts productivity. When users need to manage multiple AWS accounts or different permission roles, flexible profile switching becomes essential. This article systematically analyzes the technical implementation of temporary profile switching based on AWS CLI official documentation and community practices.

AWS CLI Profile Architecture

The AWS CLI profile system employs a layered design, with all configuration information stored by default in the ~/.aws directory. The config file contains definitions for different profiles, each distinguished by a [profile profile-name] section. This design allows users to manage multiple AWS identity credentials within the same environment, but how to temporarily switch between these profiles involves version-specific technical details.

Version Differences in Environment Variable Mechanisms

AWS CLI v1 and v2 exhibit significant differences in environment variable processing, which is the core reason behind profile switching issues. In AWS CLI v1, the system prioritizes reading the AWS_DEFAULT_PROFILE environment variable to determine the active profile. When this variable is unset, the CLI falls back to the profile named default. Therefore, the correct command to temporarily switch to the user2 profile in v1 is:

export AWS_DEFAULT_PROFILE=user2

After executing this command, all subsequent AWS CLI commands (such as aws s3 ls) will automatically use the credentials and settings from the user2 profile, without explicitly specifying the --profile parameter.

In contrast, AWS CLI v2 introduces a more simplified environment variable naming convention, using AWS_PROFILE as the primary profile selection variable. In v2, setting:

export AWS_PROFILE=user2

achieves temporary profile switching. This change reflects AWS CLI's evolution toward more intuitive API design but also introduces version compatibility challenges, particularly when users have multiple CLI versions installed or migrate between different environments.

Cross-Platform Implementation

Considering the syntax differences for environment variable settings across operating systems, temporary profile switching requires platform-specific commands. In Linux and macOS systems, use the export command to set environment variables:

export AWS_PROFILE=profile_name

In Windows systems, commands vary based on the shell type. For traditional CMD command line:

set AWS_PROFILE=profile_name

For PowerShell environments:

$env:AWS_PROFILE = 'profile_name'

These commands set environment variables in the current shell session, causing all subsequent AWS CLI commands to use the specified profile. When the shell session ends, these temporary settings automatically expire, and the system reverts to the default configuration or the environment state at the next login.

Temporary Switching vs. Persistent Configuration

Understanding the distinction between temporary switching and persistent configuration is crucial for effectively managing AWS CLI environments. Temporary switching via environment variables only affects the current shell session and its child processes. This approach is suitable for temporary task execution, testing different account permissions, or context switching within scripts.

Conversely, persistent configuration is achieved by modifying the default profile section in the ~/.aws/config file:

[default]
region = us-west-2
output = json

This modification affects all CLI commands that do not specify a profile until the configuration file is changed again. Persistent configuration is more appropriate for long-term stable working environments, while temporary switching offers greater flexibility and security, especially in multi-user shared systems or automated scripts.

Troubleshooting and Best Practices

When profile switching does not work as expected, systematic troubleshooting steps can quickly identify the issue. First, verify that environment variables are correctly set:

echo $AWS_PROFILE  # Linux/macOS
echo %AWS_PROFILE%  # Windows CMD
$env:AWS_PROFILE   # Windows PowerShell

Second, confirm the AWS CLI version, as v1 and v2 respond differently to environment variables. The aws --version command provides accurate version information. If the problem persists, check the correctness of the profile configuration itself, ensuring the target profile is properly defined in the ~/.aws/config file and that the corresponding credentials file contains valid access keys.

Best practice recommendations include: explicitly specifying profiles in scripts rather than relying on environment variables to avoid unpredictable behavior; creating dedicated profiles for different task types; regularly rotating credentials and verifying profile permission settings. For complex multi-account management scenarios, consider using AWS Organizations and cross-account roles instead of relying on multiple independent IAM user credentials.

Version Migration Considerations

When migrating from AWS CLI v1 to v2, changes in environment variable naming may break existing automation scripts and toolchains. Before migration, audit all code and configurations that depend on the AWS_DEFAULT_PROFILE environment variable, updating them to use AWS_PROFILE. Simultaneously, test critical workflows under the new version to ensure profile switching mechanisms work as expected.

For mixed environments requiring support for both v1 and v2, scripts can detect the CLI version and dynamically adjust environment variable settings:

#!/bin/bash
AWS_VERSION=$(aws --version 2>&1 | grep -o 'aws-cli/[0-9]' | cut -d'/' -f2)
if [ "$AWS_VERSION" = "1" ]; then
    export AWS_DEFAULT_PROFILE=user2
else
    export AWS_PROFILE=user2
fi

This compatibility handling ensures consistent behavior across version environments, reducing configuration issues caused by version differences.