Skip to main content

atmos auth env

Quickly generate temporary cloud credentials as environment variables so you can run tools like Terraform, AWS CLI, or SDKs without manually copying and pasting access keys. This makes it seamless to switch between identities, integrate with scripts, and keep your sessions secure and short-lived.

atmos auth env --help

Usage​

atmos auth env [--identity <name>] [--format bash|json|dotenv|env|github|credential-process] [--output-file <file>] [--login] [--min-validity <duration>]

How It Works​

atmos auth env outputs environment variable exports for a specific cloud identity (e.g., AWS_PROFILE, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE). You use this output to configure your shell environment by evaluating it with eval $(atmos auth env).

Important: This command outputs environment variables and does not perform authentication by default. It generates export statements pointing to credential files that are populated during login events. Use the --login flag to trigger authentication if credentials are missing or expired. Since commands cannot modify their parent shell's environment, you must use eval to apply these variables to your current shell.

Justification for privileged identities

Because --login performs authentication, running it against an azure/pim-role identity activates the role and therefore needs a justification. Supply it with the --justification global flag or the ATMOS_AUTH_JUSTIFICATION environment variable (resolution order: --justification > ATMOS_AUTH_JUSTIFICATION > the identity's principal.justification > interactive prompt). Without --login, atmos auth env does not authenticate and no justification is required.

Typical Workflow (AWS):

# 1. Set environment variables for an identity
eval $(atmos auth env --identity prod-admin)

# 2. Authenticate (when needed) - opens browser for SSO
atmos auth login --identity prod-admin

# 3. Use AWS CLI, Terraform, or other tools
aws s3 ls
terraform plan vpc -s prod

Typical Workflow (Azure with device-code):

# 1. Set environment variables for an Azure identity
eval $(atmos auth env --identity azure-dev)

# 2. Authenticate (when needed) - displays device code for browser login
atmos auth login --identity azure-dev

# 3. Use Azure CLI, Terraform, or other tools
az group list
terraform plan -var-file=azure.tfvars

CI/CD Workflow (GitHub Actions):

In GitHub Actions, use --format=github to export credentials directly to $GITHUB_ENV:

- name: Authenticate
  run: atmos auth env --identity azure-prod --format=github --login

- name: Deploy
  run: atmos terraform apply mycomponent -s prod

The --format=github flag writes KEY=value pairs directly to the $GITHUB_ENV file, making credentials available to subsequent steps in GitHub Actions without shell pipelines.

Minting a GitHub token in one step and consuming it in the next:

With the atmos/pro provider and github/sts integration, atmos auth env --format=github can mint a short-lived, least-privilege GitHub token in one step and hand it to later steps, all built into the Atmos CLI. Set token_env on the integration to choose the variable name the raw token is exported under:

# atmos.yaml
auth:
  providers:
    atmos-pro:
      kind: atmos/pro
      spec:
        workspace_id: <your-workspace-id>   # or ATMOS_PRO_WORKSPACE_ID
  identities:
    atmos-pro:
      kind: atmos/pro
      via: { provider: atmos-pro }
  integrations:
    github-sts:
      kind: github/sts
      via: { provider: atmos-pro }
      spec:
        token_env: GH_TOKEN                 # export the minted token as $GH_TOKEN
# .github/workflows/example.yml
permissions:
  id-token: write                            # the only permission required

steps:
  - name: Mint a GitHub token
    # Authenticates to Atmos Pro via OIDC, mints the token, and writes GH_TOKEN to $GITHUB_ENV.
    run: atmos auth env --identity=atmos-pro --format=github --login

  - name: Check out a private repo with the minted token
    uses: actions/checkout@v4
    with:
      repository: acme/private-repo
      token: ${{ env.GH_TOKEN }}

  - name: Use the GitHub CLI
    run: gh repo view acme/private-repo
    env:
      GH_TOKEN: ${{ env.GH_TOKEN }}

For Atmos's own git operations (vendoring, source: components, terraform init of private git::https://… modules) github/sts injects per-owner GIT_CONFIG_* rewrites automatically, and the single-owner token is also exported as ATMOS_PRO_GITHUB_TOKEN by default. token_env lets you export it under a different name for everything else (gh, actions/checkout, REST API). For multi-org runs, use a Go template over .owner (e.g. token_env: GH_TOKEN_{{ .owner }}) to export one variable per owner.

The commands fail gracefully: If you run cloud CLI or Terraform commands before logging in, they will fail with standard credential errors, prompting you to run atmos auth login.

This separation allows you to add eval $(atmos auth env) to your shell profile without triggering login prompts every time you open a terminal.

When to Use This Command​

Use atmos auth env when:

  • Adding authentication to your shell profile (.zshrc, .bashrc) for automatic configuration
  • Integrating with CI/CD pipelines that need environment variables
  • Writing scripts that source credentials
  • You need credentials in a specific format (bash, json, dotenv, env, github, credential-process)
  • Working primarily in a single identity and want persistent configuration

Use atmos auth shell instead when:

  • You need session isolation for security (credentials scoped to subshell)
  • Working with production or sensitive environments requiring strict boundaries
  • Running multiple concurrent sessions with different identities in separate terminals
  • You want credentials to automatically clean up when you exit the shell
  • You need clear separation between different cloud contexts

See the atmos auth shell documentation for more details on session isolation.

Examples​

# Configure shell for the default identity (bash format)
atmos auth env

# Interactively select identity
atmos auth env --identity

# JSON format for a specific identity
atmos auth env --identity prod-admin --format json

# Dotenv format
atmos auth env --format dotenv

# GitHub Actions format (writes to $GITHUB_ENV)
atmos auth env --identity prod-admin --format github

# GitHub Actions format with explicit output file
atmos auth env --identity prod-admin --format github --output-file /path/to/env/file

# AWS process-credential JSON for a credential_process profile
atmos auth env --identity prod-admin --format credential-process

# Require at least 30 minutes of remaining validity
atmos auth env --identity prod-admin --format=credential-process --min-validity=30m

# Automatically login if credentials don't exist or are expired
atmos auth env --login

# Use with identity selection and auto-login
atmos auth env --identity prod-admin --login

Shell Integration​

Adding to Your Shell Profile​

A key advantage of atmos auth env is that it outputs environment variables for an identity without requiring immediate authentication. This makes it safe to add to your shell profile without triggering a login prompt on every new shell session:

Add to ~/.bashrc or ~/.zshrc:

eval $(atmos auth env)
Helper Function for Identity Switching

For users who prefer a combined authentication and configuration flow, you can create a helper function:

# Helper function for Atmos auth integration
# Usage: use-identity [identity-name] [other atmos auth env flags]
# This uses Atmos auth to authenticate and set credentials in the environment
# If called with no arguments, it brings up the identity selector
function use-identity() {
    if ! command -v atmos >/dev/null 2>&1; then
        echo "Error: atmos command not found. Please install atmos first." >&2
        return 1
    fi

    # Run atmos auth env and evaluate the output to set credentials
    local auth_output
    if [ $# -eq 0 ]; then
        # No arguments: bring up the selector by passing --identity with no value
        if ! auth_output=$(atmos auth env --identity --login 2>&1); then
            echo "Error running atmos auth: $auth_output" >&2
            return 1
        fi
    else
        # Arguments provided: pass --identity=<value> with the first argument, then any additional flags
        if ! auth_output=$(atmos auth env --identity="$1" --login "${@:2}" 2>&1); then
            echo "Error running atmos auth: $auth_output" >&2
            return 1
        fi
    fi

    # Evaluate the output to set environment variables
    eval "$auth_output"
}

Usage examples:

# Interactively select identity and login
use-identity

# Use specific identity with automatic login
use-identity prod-admin

# Use specific identity with custom format
use-identity staging-dev --format bash

This helper function:

  • Combines configuration and authentication in one step using the --login flag
  • Checks if atmos is installed before running
  • Provides both interactive and non-interactive modes
  • Evaluates the output to set credentials in your current shell
  • Works with any cloud provider supported by Atmos

This approach:

  • Sets environment variables for the default identity
  • Uses cached credentials if they exist and are valid
  • Does not trigger login prompts - you can run atmos auth login separately when needed
  • Tools that require credentials will fail gracefully, prompting you to login when necessary

The separation between setting environment variables (atmos auth env) and authentication (atmos auth login) means you can:

  1. Set environment variables once with eval $(atmos auth env) in your profile
  2. Authenticate when needed with atmos auth login
  3. Re-authenticate when credentials expire without re-evaluating atmos auth env
Using with Warp Terminal

Warp is a modern terminal that works well with atmos auth env. When working with Warp or other feature-rich terminals, use atmos auth env instead of atmos auth shell to maintain the terminal's UI features (command palette, AI assistant, blocks, etc.).

The atmos auth shell command launches a subshell that loses the terminal emulator's feature-rich UIs. Instead, use a helper function like use-identity() (shown above) that calls atmos auth env to get credentials for AWS CLI or other operations while maintaining your terminal's interface.

Adding eval $(atmos auth env) to your shell profile (.zshrc, .bashrc) ensures that new terminal windows and panes automatically have the appropriate environment variables set for your default identity.

Flags​

--identity (alias -i)

Specify the identity to use. This flag has three modes:

  • With value (--identity admin): Use the specified identity
  • Without value (--identity): Show interactive selector to choose identity
  • Omitted: Use the default identity configured in atmos.yaml

With --format=credential-process, the interactive selector is never shown: --identity without a value and --identity=false are errors.

--format (alias -f)

Output format for the environment variables. Default: bash.

  • bash (default): Prints export KEY='value' lines suitable for shell evaluation
  • json: Prints a JSON object of environment variables
  • dotenv: Prints KEY='value' lines in dotenv format
  • env: Prints plain KEY=value lines without quoting
  • github: Prints KEY=value lines for GitHub Actions $GITHUB_ENV file. Multiline values use GitHub's heredoc syntax.
  • credential-process: Prints AWS credentials as a single JSON document in the AWS process-credential format, for use as a credential_process in ~/.aws/config. It prints credentials, not environment variables, and works only with AWS identities. It behaves exactly like atmos aws credential-process, the canonical command for this output: it never opens the interactive identity selector (so --identity needs a value or exactly one default identity must exist), it authenticates whenever the cached credentials are missing or have less than --min-validity of lifetime left, and it honors --min-validity. Unlike atmos auth login, it skips automatic integrations such as ECR login and EKS kubeconfig updates. Combining it with --login=false is an error.
atmos auth env --format=credential-process --identity=prod-admin
--output-file (alias -o)

Write output to a file instead of stdout. When used with --format=github, this specifies the target file for environment variables.

If --format=github is used without --output-file, the command automatically writes to the file specified by the $GITHUB_ENV environment variable (set automatically in GitHub Actions).

With --format=credential-process, the file holds credentials, so Atmos writes it atomically with mode 0600 (owner read and write only), replacing any existing file even when that file had looser permissions. This format never falls back to $GITHUB_ENV: without --output-file, it prints to stdout.

--login

Trigger authentication flow if credentials are missing or expired. When enabled, this flag will automatically invoke the login flow if the specified identity hasn't been authenticated yet.

  • Without flag (default): Outputs environment variables for the identity using cached credentials (if available)
  • With flag (--login): Automatically triggers browser-based authentication when credentials are missing or expired

This is particularly useful when you want to ensure fresh credentials or when switching to an identity you haven't logged into yet.

With --format=credential-process, the command always authenticates when the cached credentials are missing or about to expire, so --login is redundant and --login=false is an error.

--min-validity

Only applies to --format=credential-process: the minimum remaining lifetime for cached credentials to be reused. When the cached credentials have less than this left, Atmos authenticates again before printing, even though they have not expired yet. Default: 15m. The value must include a unit, for example 30m or 1h. Environment variable: ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY. Using the flag with another format is an error. See atmos aws credential-process for details.

atmos auth env --format=credential-process --identity=prod-admin --min-validity=30m

Environment variables​

Input Variables (Configuration)​

ATMOS_IDENTITY
Default identity when --identity is not provided.
ATMOS_AUTH_ENV_FORMAT
Sets the default output style for exported credentials. Supported values: bash, json, dotenv, env, github, credential-process.
ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY
Default for --min-validity with --format=credential-process. Shared with atmos aws credential-process.
ATMOS_AUTH_ENV_OUTPUT_FILE
Default output file path when --output-file is not provided. For --format=github, this defaults to the value of $GITHUB_ENV if set. With --format=credential-process, there is no $GITHUB_ENV fallback.

Output Variables (Exported by this command)​

When you run eval $(atmos auth env), Atmos exports provider-specific environment variables to your shell based on the identity's cloud provider.

ATMOS_IDENTITY
The name of the active identity (all providers)

Provider-specific variables:

The exact variables exported depend on your cloud provider. For example:

AWS identities:

AWS_SHARED_CREDENTIALS_FILE  # Path to Atmos-managed credentials file
AWS_CONFIG_FILE              # Path to Atmos-managed config file
AWS_PROFILE                  # Profile name for the identity
AWS_REGION                   # Default region (if configured)

Azure identities:

AZURE_SUBSCRIPTION_ID        # Azure subscription ID
AZURE_TENANT_ID              # Azure AD tenant ID
AZURE_LOCATION               # Azure region (if configured)
ARM_SUBSCRIPTION_ID          # Terraform provider subscription ID
ARM_TENANT_ID                # Terraform provider tenant ID
ARM_USE_OIDC                 # Set to "true" for OIDC authentication
ARM_USE_CLI                  # Set to "true" for CLI/device-code authentication
ARM_CLIENT_ID                # Azure AD application (client) ID for OIDC

GitHub OIDC identities:

GITHUB_TOKEN                 # GitHub authentication token
GITHUB_APP_ID                # GitHub App ID (if applicable)
GITHUB_INSTALLATION_ID       # GitHub App installation ID (if applicable)

These environment variables configure cloud provider SDKs and tools (Terraform, AWS CLI, Azure CLI, GitHub CLI, kubectl) to use the correct credentials without exposing them directly in the environment.

Notes​

  • atmos auth env outputs environment variable export statements. You must use eval to apply them to your current shell session, where they persist until you close the shell or override them.
  • The command does not trigger authentication unless you use the --login flag.
  • Safe to add to shell profiles (.zshrc, .bashrc) - won't prompt for login on every shell startup.
  • Tools expecting credentials will fail gracefully if you haven't run atmos auth login yet, prompting you to authenticate.
  • For workflows requiring multiple identities simultaneously, consider using atmos auth shell which provides session isolation.

See Also​