commands-reference.md19.8 KB

Auth Commands Reference

Complete reference for all atmos auth subcommands, flags, and usage patterns.

Common Flag: --identity

All auth commands that accept --identity (alias -i) support three modes:

With value (--identity admin): Use the specified identity.
Without value (--identity): Force interactive selector, even if a default is configured.
Omitted: Use the default identity, or prompt if no default is set.

Environment variables: ATMOS_IDENTITY or IDENTITY (checked in that order).

Set ATMOS_IDENTITY=false (or 0, no, off) to disable Atmos-managed authentication entirely.

atmos auth login

Authenticate with a configured identity using SSO, SAML, OIDC, or static credentials. Credentials are cached to avoid repeated logins until expiration.

atmos auth login [--identity <name>] [--provider <name>]

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to authenticate (see common flag above)
`--provider`	`-p`	Authenticate directly with a provider (bypasses identity selection)

Examples

atmos auth login                        # Default identity
atmos auth login --identity             # Interactive selector
atmos auth login --identity admin       # Specific identity
atmos auth login -i admin               # Short form
atmos auth login --provider company-sso # Direct provider auth (for auto_provision_identities)

Notes

Prints provider, identity, account, region, and expiration on success.
For AWS SSO, a device verification code is displayed in the terminal (not an MFA token).
For Azure device code authentication, a verification code and URL are shown for browser auth.
Automatically triggers ECR integrations with auto_provision: true.
When no identities are configured and --provider is omitted, Atmos auto-selects a single provider or prompts for selection if multiple providers exist.

atmos auth whoami

Display the current authentication context: effective identity, credentials, account, region, and expiration.

atmos auth whoami [--identity <name>] [--output json]

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to inspect
`--output`	`-o`	Output format: `json` (default is human-readable)

Environment Variables

Variable	Purpose
`ATMOS_IDENTITY`	Default identity
`ATMOS_AUTH_WHOAMI_OUTPUT`	Set to `json` for default JSON output

Examples

atmos auth whoami                       # Default identity, human-readable
atmos auth whoami --identity dev-admin  # Specific identity
atmos auth whoami --output json         # JSON output (redacts home directory from paths)
atmos auth whoami -i                    # Interactive selector

atmos auth validate

Validate the auth configuration in atmos.yaml for syntax errors, missing required fields, circular dependency chains, and logical inconsistencies.

atmos auth validate [--verbose]

Flags

Flag	Alias	Description
`--verbose`	`-v`	Enable verbose validation output

Environment Variables

Variable	Purpose
`ATMOS_AUTH_VALIDATE_VERBOSE`	Set to `true` to enable verbose by default

Examples

atmos auth validate                     # Basic validation
atmos auth validate --verbose           # Verbose output with details

atmos auth shell

Launch an interactive shell with all cloud credentials pre-configured. The shell inherits your $SHELL preference and supports custom arguments. Use for interactive sessions with multiple commands.

atmos auth shell [--identity <name>] [--shell <path>] [-- <shell-args>...]

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to use for authentication
`--shell`		Shell program (defaults to `$SHELL`, then `bash`, then `sh`; `cmd.exe` on Windows)

Arguments

Argument	Description
`shell-args...`	Optional shell arguments after `--` (default: `-l` for login shell)

Environment Variables Set in Shell

Variable	Description
`ATMOS_IDENTITY`	Name of the authenticated identity
`ATMOS_SHLVL`	Shell nesting level (increments for nested shells)
`AWS_SHARED_CREDENTIALS_FILE`	Path to Atmos-managed credentials file (AWS)
`AWS_CONFIG_FILE`	Path to Atmos-managed config file (AWS)
`AWS_PROFILE`	Profile name for the identity (AWS)

Examples

atmos auth shell                                        # Default shell, default identity
atmos auth shell --identity prod-admin                  # Specific identity
atmos auth shell --shell /bin/zsh                       # Override shell
atmos auth shell -- -c "env | grep AWS"                 # Pass shell args
atmos auth shell -- --norc                              # Skip shell config loading
atmos auth shell --identity staging --shell /bin/bash -- -c "terraform plan"

Notes

Type exit or press Ctrl+D to leave the shell.
Credentials are written to managed config files (XDG-compliant), not exposed directly as env vars.
Environment variables from authentication take precedence over existing values.

atmos auth exec

Run a single command with identity credentials injected into the environment. Use for one-off commands or automation where shell isolation is not needed.

atmos auth exec [--identity <name>] -- <command> [args...]

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to use for authentication

Arguments

Argument	Description
`command`	Program to execute with auth env vars set
`args...`	Arguments passed through to the command

Examples

# AWS examples
atmos auth exec -- terraform plan -var-file=env.tfvars
atmos auth exec --identity prod-admin -- aws sts get-caller-identity
atmos auth exec -- env | grep AWS

# Azure examples
atmos auth exec --identity azure-dev -- az group list
atmos auth exec --identity azure-prod -- terraform plan -var-file=azure.tfvars
atmos auth exec -- env | grep -E '^(AZURE_|ARM_)'

# CI/CD examples
atmos auth exec --identity azure-prod -- terraform apply -auto-approve

Notes

-- is required to separate Atmos flags from the subcommand.
The command inherits all Atmos-configured credentials and environment variables.

atmos auth env

Output credential environment variables for shell evaluation. Does not perform authentication by default.

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

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to use
`--format`	`-f`	Output format: `bash` (default), `json`, `dotenv`, `env` (plain `KEY=value`), `github` (`$GITHUB_ENV` lines), `credential-process` (AWS process-credential JSON; alias of `atmos aws credential-process`)
`--output-file`	`-o`	Write output to a file instead of stdout. `github` defaults to `$GITHUB_ENV`. `credential-process` writes the file atomically with mode `0600` and never falls back to `$GITHUB_ENV`.
`--login`		Trigger authentication if credentials are missing or expired. With `credential-process`, `--login=false` is an error.
`--min-validity`		`credential-process` only: refresh cached credentials with less than this lifetime left. Default `15m`. Needs a unit (for example `30m`). Other formats reject it.

Environment Variables

Variable	Purpose
`ATMOS_IDENTITY`	Default identity
`ATMOS_AUTH_ENV_FORMAT`	Default output format
`ATMOS_AUTH_ENV_OUTPUT_FILE`	Default output file
`ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY`	Default for `--min-validity` (`credential-process` format)

Output Variables (AWS)

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)

Output Variables (Azure)

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

Examples

# Set environment in current shell
eval $(atmos auth env)
eval $(atmos auth env --identity prod-admin)

# JSON output for scripting
atmos auth env --identity prod-admin --format json

# Dotenv format
atmos auth env --format dotenv

# Auto-login if credentials missing
atmos auth env --login
eval $(atmos auth env --identity prod-admin --login)

# PowerShell
$envVars = atmos auth env --format json | ConvertFrom-Json
$envVars.PSObject.Properties | ForEach-Object { Set-Item -Path "Env:$($_.Name)" -Value $_.Value }

Shell Profile Integration

Safe to add to ~/.bashrc or ~/.zshrc -- does not trigger login prompts:

eval $(atmos auth env)

atmos aws credential-process

Print AWS credentials for an Atmos identity in the AWS process-credential JSON format, so a credential_process profile in ~/.aws/config can delegate to Atmos.

atmos aws credential-process --identity=<name> [--min-validity=15m]

Alias with the same output: atmos auth env --format=credential-process --identity=<name>.

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to print credentials for. Resolved from the flag, then `ATMOS_IDENTITY`, then the single `default: true` identity. Never prompts: required unless exactly one default identity exists.
`--min-validity`		Reuse cached credentials only while more than this lifetime remains. Default `15m`. Needs a unit (for example `30m`). Environment variable: `ATMOS_AWS_CREDENTIAL_PROCESS_MIN_VALIDITY`.

Output

One JSON document on stdout, unmasked; logs go to stderr:

{"Version":1,"AccessKeyId":"ASIA...","SecretAccessKey":"...","SessionToken":"...","Expiration":"2026-10-02T18:30:00Z"}

SessionToken and Expiration are omitted for long-lived keys.

Examples

# ~/.aws/config (--chdir is the most robust way to find atmos.yaml from any directory)
[profile app-sandbox-1]
credential_process = atmos --chdir=/path/to/infrastructure aws credential-process --identity=app-sandbox-1
region = us-east-1

# Alternatives: --config-path=/path/to/infrastructure, ATMOS_CLI_CONFIG_PATH, or a global ~/.atmos/atmos.yaml

aws sts get-caller-identity --profile=app-sandbox-1

Notes

Cached credentials with more than --min-validity left print with no network call. Otherwise Atmos authenticates like atmos auth login, but skips integrations (ECR login, EKS kubeconfig).
Prompts need both stdin and stderr to be terminals. The AWS CLI captures stderr, so when an interactive login is required (for example an expired SSO session), the command fails fast with a hint. Run atmos auth login --identity=<name> first.
For identities defined in an Atmos profile, add Atmos's --profile=<name> (or ATMOS_PROFILE) to the credential_process line. It is not aws --profile.
Works with AWS identities only.
Full recipes and troubleshooting: aws-credential-process.md.

atmos auth console

Open cloud provider web console in your default browser using authenticated credentials.

atmos auth console [--identity <name>] [--destination <url-or-alias>] [--duration <duration>]
                    [--issuer <name>] [--print-only] [--no-open]

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to use for console access
`--destination`		Console page URL or AWS service alias (e.g., `s3`, `ec2`, `lambda`)
`--duration`		Console session duration (Go format, e.g., `4h`; max 12h for AWS)
`--issuer`		Identifier in console URL (default: `atmos`; AWS only)
`--print-only`		Print URL to stdout without opening browser
`--no-open`		Display URL but do not open browser

Provider Support

Provider	Status
AWS (IAM Identity Center)	Supported
AWS (SAML)	Supported
Azure	Supported (opens Azure Portal)
GCP	Planned

Examples

atmos auth console                                      # Default identity, main console
atmos auth console --identity prod-admin                # Specific identity
atmos auth console --destination s3                     # AWS S3 console (alias)
atmos auth console --destination ec2 --duration 4h      # EC2 with custom duration
atmos auth console --destination https://console.aws.amazon.com/cloudformation
atmos auth console --print-only | pbcopy                # Copy URL to clipboard (macOS)
atmos auth console --no-open                            # Display URL only
atmos auth console --issuer devops-team --duration 2h   # Custom issuer

Notes

AWS console sign-in tokens are valid for 15 minutes (to click the link). Console session duration is separate.
100+ AWS service aliases supported: s3, ec2, lambda, dynamodb, rds, vpc, iam, eks, etc.
Requires temporary credentials with session token (not permanent IAM user credentials).

atmos auth list

List all configured authentication providers and identities with their relationships and chains.

atmos auth list [--format <format>] [--providers [names]] [--identities [names]]

Flags

Flag	Alias	Description
`--format`	`-f`	Output format: `table` (default), `tree`, `json`, `yaml`, `graphviz`/`dot`, `mermaid`, `markdown`/`md`
`--providers`		Show only providers (optionally filter by comma-separated names)
`--identities`		Show only identities (optionally filter by comma-separated names)

--providers and --identities are mutually exclusive.

Examples

atmos auth list                                 # Table format (default)
atmos auth list --providers                     # Providers only
atmos auth list --providers=aws-sso,okta        # Specific providers
atmos auth list --identities                    # Identities only
atmos auth list --identities=admin,developer    # Specific identities
atmos auth list --format tree                   # Hierarchical tree view
atmos auth list --format json                   # JSON for programmatic access
atmos auth list --format yaml                   # YAML output
atmos auth list --format graphviz > auth.dot    # Graphviz DOT format
atmos auth list --format mermaid                # Mermaid diagram syntax
atmos auth list --format markdown > auth.md     # Markdown with embedded Mermaid

Visualization

# Generate PNG diagram
atmos auth list --format graphviz | dot -Tpng > auth.png

# Generate SVG
atmos auth list --format graphviz | dot -Tsvg > auth.svg

Table Columns

Providers: NAME, KIND, REGION, START URL/URL, DEFAULT. Identities: NAME, KIND, VIA PROVIDER, VIA IDENTITY, DEFAULT, ALIAS.

atmos auth ecr-login

Login to AWS Elastic Container Registry using integrations or explicit registry URLs. Writes Docker credentials to ~/.docker/config.json.

atmos auth ecr-login [integration] [--identity <name>] [--registry <url>]

Arguments

Argument	Description
`integration`	Named integration from `auth.integrations` (e.g., `dev/ecr/primary`)

Flags

Flag	Alias	Description
`--identity`	`-i`	Execute all ECR integrations linked to this identity
`--registry`	`-r`	Explicit registry URL(s) for ad-hoc login (can be repeated)

Examples

# Named integration
atmos auth ecr-login dev/ecr/primary

# All integrations for an identity
atmos auth ecr-login --identity dev-admin

# Explicit registry URL
atmos auth ecr-login --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Multiple explicit registries
atmos auth ecr-login \
  --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com \
  --registry 987654321098.dkr.ecr.us-west-2.amazonaws.com

Notes

ECR tokens expire after approximately 12 hours (AWS-enforced).
Requires IAM permission: ecr:GetAuthorizationToken.
Only private ECR registries are supported (not ECR Public or China/GovCloud).
Respects DOCKER_CONFIG environment variable for credential file location.

atmos auth logout

Remove locally cached credentials and session data. Preserves keychain credentials by default for faster re-authentication.

atmos auth logout [identity] [--identity <name>] [--all] [--provider <name>]
                  [--keychain] [--force] [--dry-run]

Arguments

Argument	Description
`identity`	Name of identity to logout from (alternative to `--identity` flag)

Flags

Flag	Alias	Description
`--identity`	`-i`	Identity to logout from
`--all`		Logout from all identities and providers
`--provider`		Logout from a specific provider (clears all its identities)
`--keychain`		Also delete credentials from system keychain (destructive)
`--force`		Skip interactive confirmation prompts (for CI/CD with `--keychain`)
`--dry-run`		Preview what would be removed without deleting

What Gets Removed

Command	Keychain	Session Data	Config Files
`logout <identity>`	Preserved	Cleared	Identity profile removed
`logout <identity> --keychain`	Deleted	Cleared	Identity profile removed
`logout --provider <name>`	Preserved	Cleared	Entire provider directory
`logout --all`	Preserved	Cleared	All profiles removed
Add `--keychain` to any	Deleted	Cleared	Same as without

Examples

atmos auth logout dev-admin                     # Logout specific identity (safe)
atmos auth logout --all                         # Logout all (preserves keychain)
atmos auth logout --provider aws-sso            # Logout all identities for provider
atmos auth logout dev-admin --keychain          # Delete keychain creds (interactive confirm)
atmos auth logout dev-admin --keychain --force  # Delete keychain creds (no confirm, for CI/CD)
atmos auth logout --all --dry-run               # Preview what would be removed
atmos auth logout                               # Interactive mode (no arguments)

Notes

Browser sessions with identity providers remain active -- sign out from IdP separately.
Uses best-effort cleanup: continues even if individual steps fail.
Exit code 0 as long as at least one credential was removed.
All logout operations are logged for security auditing (use ATMOS_LOGS_LEVEL=Debug).

Debugging Authentication

Enable Debug Logging

# Verbose CLI output
atmos auth validate --verbose

# Set log level
ATMOS_LOGS_LEVEL=Debug atmos auth whoami

# Write auth logs to file
# In atmos.yaml:
auth:
  logs:
    level: Debug
    file: /tmp/atmos-auth.log

Common Troubleshooting Commands

# Validate configuration
atmos auth validate --verbose

# Check current status
atmos auth whoami

# Re-authenticate
atmos auth login --identity <name>

# Verify assumed role
atmos auth exec --identity <name> -- aws sts get-caller-identity

# Check exported environment
atmos auth env --identity <name>
atmos auth exec --identity <name> -- env | grep AWS