Posted inTechnology

Working with AWS CLI Environment Variables: A Practical Guide

Working with AWS CLI Environment Variables: A Practical Guide

Environment variables are a lightweight, portable way to configure the AWS Command Line Interface (CLI) without hardcoding values in files or scripts. Understanding how to use AWS CLI environment variables can speed up development, simplify automation, and keep credentials secure when interacting with AWS services. This guide walks through the common variables, how to set them across platforms, best practices, and practical troubleshooting tips.

What are AWS CLI environment variables?

Environment variables are key-value pairs inherited by processes from the operating system. For the AWS CLI, certain environment variables can override values stored in configuration files or profiles. This gives you a flexible mechanism to switch credentials, regions, or profiles on the fly—useful in local development, CI/CD pipelines, or ephemeral testing environments. By using AWS CLI environment variables, you can avoid editing the ~/.aws directory and keep sensitive data out of source control, while still enabling automated workflows that require access to AWS resources.

Common AWS CLI environment variables

The most frequently used AWS CLI environment variables fall into a few categories: credentials, region, and profile management. Here are the core variables you’ll encounter, along with a concise description of each.

  • AWS_ACCESS_KEY_ID — The access key ID associated with an AWS account or role. This value identifies the user or service making API calls.
  • AWS_SECRET_ACCESS_KEY — The secret key corresponding to the access key ID. This credential should be kept private and never exposed in logs or source code.
  • AWS_SESSION_TOKEN — A temporary session token that often accompanies temporary credentials (for example, when using AWS STS or federation). It is required when the credentials are not long-lived.
  • AWS_DEFAULT_REGION — The preferred AWS region for API calls if no explicit region is supplied in the command. This helps ensure consistent endpoints across commands.
  • AWS_REGION — An alias for AWS_DEFAULT_REGION in many contexts; both can be used to influence the region selection.
  • AWS_PROFILE — The name of an AWS CLI profile to use from the credentials/config files. This allows switching between multiple sets of credentials without changing code.
  • AWS_CONFIG_FILE — Path to a custom AWS config file. Useful when you want to point the CLI to a separate configuration file instead of the default location.
  • AWS_SHARED_CREDENTIALS_FILE — Path to a custom credentials file. This is handy when you maintain credentials in an alternate path or per-project setup.

In most day-to-day scenarios, you’ll set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_DEFAULT_REGION. When you work with temporary credentials or multiple accounts, AWS_SESSION_TOKEN and AWS_PROFILE become essential to keep operations smooth and secure.

Setting environment variables across platforms

Platform differences matter when configuring AWS CLI environment variables. Below are practical commands you can adapt for Windows, macOS, and Linux environments. Each approach shows how to set values in a way that the AWS CLI can immediately pick up.

macOS and Linux (bash, zsh, or similar shells)

# Temporary for the current shell session
export AWS_ACCESS_KEY_ID="AKIAEXAMPLE"
export AWS_SECRET_ACCESS_KEY="wJalrXUtnFexampleSecret"
export AWS_SESSION_TOKEN="IQoJb3JpZ2luX2VjEO3..."
export AWS_DEFAULT_REGION="us-west-2"

# Optionally set a profile to influence other config lookups
export AWS_PROFILE="my-dev-profile"

# If you want to override config or credentials file locations
export AWS_CONFIG_FILE="$HOME/.aws/config-custom"
export AWS_SHARED_CREDENTIALS_FILE="$HOME/.aws/credentials-custom"

To remove these in the current session, you can unset or unset with values:

unset AWS_ACCESS_KEY_ID
unset AWS_SECRET_ACCESS_KEY
unset AWS_SESSION_TOKEN
unset AWS_DEFAULT_REGION
unset AWS_PROFILE
unset AWS_CONFIG_FILE
unset AWS_SHARED_CREDENTIALS_FILE

Windows Command Prompt (cmd.exe)

set AWS_ACCESS_KEY_ID=AKIAEXAMPLE
set AWS_SECRET_ACCESS_KEY=wJalrXUtnFexampleSecret
set AWS_SESSION_TOKEN=IQoJb3JpZ2luX2VjEO3...
set AWS_DEFAULT_REGION=us-west-2

set AWS_PROFILE=my-dev-profile
set AWS_CONFIG_FILE=%USERPROFILE%\.aws\config-custom
set AWS_SHARED_CREDENTIALS_FILE=%USERPROFILE%\.aws\credentials-custom

Windows PowerShell

$env:AWS_ACCESS_KEY_ID = "AKIAEXAMPLE"
$env:AWS_SECRET_ACCESS_KEY = "wJalrXUtnFexampleSecret"
$env:AWS_SESSION_TOKEN = "IQoJb3JpZ2luX2VjEO3..."
$env:AWS_DEFAULT_REGION = "us-west-2"

$env:AWS_PROFILE = "my-dev-profile"
$env:AWS_CONFIG_FILE = "$HOME\.aws\config-custom"
$env:AWS_SHARED_CREDENTIALS_FILE = "$HOME\.aws\credentials-custom"

These examples demonstrate how to apply environment variables quickly. In production or CI environments, you might wire these commands into a script or pipeline steps to ensure consistent behavior across stages.

Best practices for using AWS CLI environment variables

While environment variables offer flexibility, they also require careful handling to maintain security and reliability. Consider the following practices to maximize their value.

  • Prefer temporary credentials when possible. Use AWS STS or session tokens for short-lived access, especially in CI/CD workflows. This reduces risk if a token is exposed.
  • Leverage profiles to manage multiple accounts. AWS_PROFILE makes it easy to switch contexts without editing code or scripts. Maintain distinct credential files for each environment.
  • Keep credentials out of logs and command histories. Be mindful that many shells log commands. Avoid echoing credentials or printing environment variables in verbose builds.
  • Source control considerations. Do not commit credentials or secret tokens. Store them in secure secret managers or encrypted storage, and reference them via short-lived tokens where feasible.
  • Centralize configuration when possible. Use a consistent approach for setting AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE across teams to reduce confusion.
  • Use least privilege principle. Assign just enough permissions to the credentials you expose through environment variables. Rotate keys regularly and monitor usage.
  • Automation-friendly naming. Name profiles and files clearly to reflect the environment (dev, staging, prod) to avoid cross-environment mistakes.

Debugging and verification tips

When something doesn’t work as expected, a few quick checks can save a lot of time. Verifying that the AWS CLI picks up the environment variables is straightforward and fast.

  • Inspect active credentials with aws sts get-caller-identity. If the call succeeds, your credentials and region configuration are in place.
  • Show the current configuration using aws configure list to see which credentials and region the CLI is using and whether a profile is active.
  • List environment variables in your shell to confirm values are set, for example printenv | grep AWS_ on Unix-like systems or Get-ChildItem Env:AWS_ in PowerShell.
  • Test region-specific commands such as listing S3 buckets in the chosen region to verify endpoint availability and permissions.

Security considerations

Security should be a central concern when using AWS CLI environment variables. Since credentials can grant access to your AWS resources, follow these guidelines to minimize risk.

  • Avoid exposing credentials in logs or error messages. Do not print AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, or AWS_SESSION_TOKEN in logs.
  • Limit scope with temporary credentials. Whenever possible, prefer short-lived tokens and rotate them regularly in your automation pipelines.
  • Do not store credentials in public repositories. Keep sensitive files secure and access-controlled, especially AWS config or credentials files referenced by environment variables.
  • Use MFA and role-based access where suitable. Where feasible, require MFA for sensitive operations and map credentials to roles with restricted permissions.
  • Audit and monitor usage. Enable CloudTrail and monitor access patterns to detect unusual activity tied to credentials used via environment variables.

Conclusion

AWS CLI environment variables offer a pragmatic approach to managing credentials, regions, and profiles across local development, testing, and automation. By understanding the core variables—such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_PROFILE, AWS_CONFIG_FILE, and AWS_SHARED_CREDENTIALS_FILE—you can control how the CLI authenticates and where it operates without altering repository or system configurations. Following best practices for security, rotation, and least privilege, combined with clear verification steps, will help you maintain a robust and efficient workflow when working with AWS resources. Embrace environment variables as a valuable tool in your AWS toolkit and tailor their use to your team’s needs and security posture.