Skip to main content

Environment Variables

Most YAML settings in atmos.yaml can also be defined by environment variables. This is helpful for local development, CI/CD pipelines, and environment-specific overrides.

Configuration Variables​

These environment variables configure Atmos behavior and can override settings in atmos.yaml.

ATMOS_CLI_CONFIG_PATH

Where to find atmos.yaml. Path to a folder where atmos.yaml CLI config file is located (e.g. /config).

ATMOS_CONFIG

Paths to specific configuration files (comma-separated). Equivalent to --config.

ATMOS_CONFIG_PATH

Paths to search for Atmos configuration (comma-separated). Equivalent to --config-path.

ATMOS_PROFILE

Activate configuration profiles (comma-separated). Equivalent to the --profile flag.

ATMOS_BASE_PATH

Base path to components and stacks folders.

  • YAML Path: base_path
ATMOS_CHDIR

Change the working directory before executing any command. Equivalent to --chdir.

ATMOS_VENDOR_BASE_PATH

Path to vendor configuration file or directory containing vendor files.

  • YAML Path: vendor.base_path

Version Management​

ATMOS_USE_VERSION

Specify which version of Atmos to use. If the running version doesn't match, Atmos automatically downloads and re-executes with the requested version. Equivalent to --use-version.

  • Example: ATMOS_USE_VERSION=1.160.0 atmos terraform plan
ATMOS_VERSION

Convenience alias for ATMOS_USE_VERSION.

ATMOS_VERSION_ENFORCEMENT

Version constraint enforcement mode. Controls behavior when version constraints are defined in atmos.yaml.

Terminal and Output Variables​

ATMOS_NO_COLOR

Disable colored output. Equivalent to --no-color.

NO_COLOR

Standard convention to disable colored output. Recognized alongside ATMOS_NO_COLOR.

ATMOS_FORCE_COLOR

Force TrueColor output even when terminal detection says otherwise. Equivalent to --force-color.

ATMOS_FORCE_TTY

Force TTY mode for terminal output. Equivalent to --force-tty.

COLUMNS

Standard convention supplying the terminal width when output is not a TTY (pipes, recordings, CI). Atmos lays out width-sensitive output (such as help screens) at this width. Ignored when a real terminal size is available; capped by settings.terminal.max_width when configured.

ATMOS_REDIRECT_STDERR

Redirect stderr to a file. Equivalent to --redirect-stderr.

Component Variables​

ATMOS_COMPONENTS_TERRAFORM_COMMAND

The executable to be called by atmos when running Terraform commands.

  • YAML Path: components.terraform.command
ATMOS_COMPONENTS_TERRAFORM_BASE_PATH

Base path to Terraform components.

  • YAML Path: components.terraform.base_path
ATMOS_COMPONENTS_TERRAFORM_APPLY_AUTO_APPROVE

If set to true, auto-approve Terraform apply.

  • YAML Path: components.terraform.apply_auto_approve
ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INIT

Run terraform init when executing atmos terraform deploy command.

  • YAML Path: components.terraform.deploy_run_init
ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE

Run terraform init -reconfigure when executing atmos terraform commands. Deprecated in favor of ATMOS_COMPONENTS_TERRAFORM_INIT_RECONFIGURE.

  • YAML Path: components.terraform.init_run_reconfigure
ATMOS_COMPONENTS_TERRAFORM_INIT_MODE

Controls when Atmos runs terraform init automatically: auto (default, skip when nothing relevant changed), always, or never.

  • YAML Path: components.terraform.init.mode
ATMOS_COMPONENTS_TERRAFORM_INIT_RECONFIGURE

Controls when Atmos adds -reconfigure to an automatic terraform init: auto (default, only when the backend changed), always, or never.

  • YAML Path: components.terraform.init.reconfigure
ATMOS_COMPONENTS_TERRAFORM_INIT_UPGRADE

Controls when Atmos adds -upgrade to an automatic terraform init: never (default), auto (only when Terraform/OpenTofu reports it's required), or always.

  • YAML Path: components.terraform.init.upgrade
ATMOS_COMPONENTS_TERRAFORM_INIT_PASS_VARS

Pass the generated varfile to terraform init using the --var-file flag.

  • YAML Path: components.terraform.init.pass_vars
ATMOS_COMPONENTS_TERRAFORM_PLAN_SKIP_PLANFILE

Skip writing the plan to a file by not passing the -out flag.

  • YAML Path: components.terraform.plan.skip_planfile
ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE

If set to true, auto-generate Terraform backend config files.

  • YAML Path: components.terraform.auto_generate_backend_file
ATMOS_COMPONENTS_TERRAFORM_PLUGIN_CACHE

If set to true, enable Terraform provider plugin caching.

  • YAML Path: components.terraform.plugin_cache
ATMOS_COMPONENTS_TERRAFORM_PLUGIN_CACHE_DIR

Custom directory for Terraform provider plugin cache. If not set, uses the XDG cache directory.

  • YAML Path: components.terraform.plugin_cache_dir
ATMOS_COMPONENTS_TERRAFORM_CACHE_ENABLED

If set to true, enable the Terraform registry cache proxy for provider and module registry traffic.

  • YAML Path: components.terraform.cache.enabled
  • Default: false
ATMOS_COMPONENTS_TERRAFORM_CACHE_LOCATION

Custom root directory for the Terraform registry cache. Pin this to a stable path in CI when the cache should be reused across atmos invocations.

  • YAML Path: components.terraform.cache.location
ATMOS_COMPONENTS_TERRAFORM_AUTO_PROVISION_WORKDIR_FOR_OUTPUTS

If set to false, disable automatic JIT workdir provisioning before terraform init during !terraform.output / atmos.Component evaluation.

  • YAML Path: components.terraform.auto_provision_workdir_for_outputs
  • Default: true
ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK_TIMEOUT

Default value for terraform's -lock-timeout flag (e.g. 5m). Overrides the atmos.yaml value; overridden by stack-level, component-level, and CLI-typed flags. See Flags.

  • YAML Path: components.terraform.flags.lock_timeout
ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK

Default value for terraform's -lock flag.

  • YAML Path: components.terraform.flags.lock
ATMOS_COMPONENTS_TERRAFORM_FLAGS_PARALLELISM

Default value for terraform's -parallelism flag.

  • YAML Path: components.terraform.flags.parallelism
ATMOS_COMPONENTS_TERRAFORM_FLAGS_REFRESH

Default value for terraform's -refresh flag.

  • YAML Path: components.terraform.flags.refresh
ATMOS_COMPONENTS_TERRAFORM_FLAGS_COMPACT_WARNINGS

Default value for terraform's -compact-warnings flag.

  • YAML Path: components.terraform.flags.compact_warnings
  • Default: false
ATMOS_COMPONENTS_HELMFILE_COMMAND

The executable to be called by atmos when running Helmfile commands.

  • YAML Path: components.helmfile.command
ATMOS_COMPONENTS_HELMFILE_BASE_PATH

Path to helmfile components.

  • YAML Path: components.helmfile.base_path
ATMOS_COMPONENTS_HELMFILE_USE_EKS

If set to true, download kubeconfig from EKS before executing atmos helmfile commands.

  • YAML Path: components.helmfile.use_eks
ATMOS_COMPONENTS_HELMFILE_KUBECONFIG_PATH

Path to write the kubeconfig file.

  • YAML Path: components.helmfile.kubeconfig_path
ATMOS_COMPONENTS_HELMFILE_HELM_AWS_PROFILE_PATTERN

Pattern for AWS profile to use when executing atmos helmfile commands.

  • YAML Path: components.helmfile.helm_aws_profile_pattern
ATMOS_COMPONENTS_HELMFILE_CLUSTER_NAME_PATTERN

Pattern for EKS cluster name to use when executing atmos helmfile commands.

  • YAML Path: components.helmfile.cluster_name_pattern

Stack Variables​

ATMOS_STACKS_BASE_PATH

Base path to Atmos stack manifests.

  • YAML Path: stacks.base_path
ATMOS_STACKS_INCLUDED_PATHS

List of paths to use as top-level stack manifests.

  • YAML Path: stacks.included_paths
ATMOS_STACKS_EXCLUDED_PATHS

List of paths to not consider as top-level stacks.

  • YAML Path: stacks.excluded_paths
ATMOS_STACKS_NAME_PATTERN

Stack name pattern to use as Atmos stack names.

  • YAML Path: stacks.name_pattern
ATMOS_STACKS_NAME_TEMPLATE

Stack name Golang template to use as Atmos stack names.

  • YAML Path: stacks.name_template

Workflow and Schema Variables​

ATMOS_WORKFLOWS_BASE_PATH

Base path to Atmos workflows.

  • YAML Path: workflows.base_path
ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH

Base path to JSON schemas for component validation.

  • YAML Path: schemas.jsonschema.base_path
ATMOS_SCHEMAS_OPA_BASE_PATH

Base path to OPA policies for component validation.

  • YAML Path: schemas.opa.base_path
ATMOS_SCHEMAS_ATMOS_MANIFEST

Path to JSON Schema to validate Atmos stack manifests.

  • YAML Path: schemas.atmos.manifest

Logging and Profiling Variables​

ATMOS_LOGS_FILE

The file to write Atmos logs to (/dev/stdout, /dev/stderr, /dev/null, or a file path).

  • YAML Path: logs.file
ATMOS_LOGS_LEVEL

Logs level: Trace, Debug, Info, Warning, Off.

  • YAML Path: logs.level
ATMOS_PROFILER_ENABLED

Enable or disable the pprof HTTP profiling server.

  • YAML Path: profiler.enabled
ATMOS_PROFILER_HOST

Host address for the profiling server.

  • YAML Path: profiler.host
ATMOS_PROFILER_PORT

Port for the profiling server.

  • YAML Path: profiler.port
ATMOS_PROFILE_FILE

Write profiling data to the specified file.

  • YAML Path: profiler.file
ATMOS_PROFILE_TYPE

Type of profile to collect: cpu, heap, allocs, goroutine, block, mutex, threadcreate, trace.

  • YAML Path: profiler.profile_type

Settings Variables​

ATMOS_SETTINGS_LIST_MERGE_STRATEGY

Specifies how lists are merged: replace, append, merge.

  • YAML Path: settings.list_merge_strategy
ATMOS_VERSION_CHECK_ENABLED

Enable/disable Atmos version checks for updates.

  • YAML Path: version.check.enabled

Authentication and Token Injection​

GITHUB_TOKEN / ATMOS_GITHUB_TOKEN

GitHub token for private module downloads and API access. ATMOS_GITHUB_TOKEN takes precedence over GITHUB_TOKEN. Automatically injected into Terraform environments when ATMOS_INJECT_GITHUB_TOKEN=true (default).

ATMOS_PRO_GITHUB_TOKEN

GitHub token for private module downloads and Atmos-native git operations (vendoring, source: provisioning, go-getter), preferred ahead of ATMOS_GITHUB_TOKEN and GITHUB_TOKEN. Typically a token brokered by Atmos Pro.

ATMOS_INJECT_GITHUB_TOKEN

Inject the GitHub token into component environments. Default: true. Set to false to prevent token injection.

ATMOS_GITHUB_CLI

Name (or path) of the GitHub CLI used to obtain a token when no GITHUB_TOKEN / ATMOS_GITHUB_TOKEN is set. Defaults to gh. Atmos runs <cli> auth token only as a last resort, after the flag and environment variables. Set it to an empty value to disable the CLI fallback entirely, or to a nonexistent binary to force anonymous (unauthenticated) GitHub access — useful for testing the public artifact/download paths (subject to GitHub's 60 requests/hour unauthenticated rate limit).

GITHUB_USERNAME / GITHUB_ACTOR / ATMOS_GITHUB_USERNAME

GitHub username for OCI registry authentication to ghcr.io. GITHUB_ACTOR is automatically set in GitHub Actions.

  • YAML Path: settings.github_username
GITLAB_TOKEN / ATMOS_GITLAB_TOKEN

GitLab token for private module downloads.

ATMOS_INJECT_GITLAB_TOKEN

Inject the GitLab token into component environments.

BITBUCKET_TOKEN / ATMOS_BITBUCKET_TOKEN

App password for Bitbucket API requests and private module downloads.

ATMOS_INJECT_BITBUCKET_TOKEN

Inject the Bitbucket token into component environments.

BITBUCKET_USERNAME

Username for Bitbucket authentication. Bitbucket requires a valid username and does not accept dummy values like x-access-token.

GitHub Enterprise Server (GHES)​

These variables point Atmos at a GitHub Enterprise Server instance instead of public github.com. GITHUB_SERVER_URL and GITHUB_API_URL are the same variables GitHub Actions already exports on both github.com and GHES runners, so CI configuration typically needs no changes.

The toolchain (aqua-registry tools and their release assets) is a separate concern from where your own repositories live: aqua-registry tools are hosted on public github.com even when your repositories are on GHES, so the toolchain does not follow GITHUB_SERVER_URL / GITHUB_API_URL. Use the ATMOS_TOOLCHAIN_* variables instead — for example, to point the toolchain at a corporate release proxy or mirror.

GITHUB_SERVER_URL

Base URL of the GitHub (or GHES) web/clone host for your own repositories. Default: https://github.com. Used by the CI provider, imports/vendoring raw fetches, the pkg/github API client (releases, tags, artifacts), the token host allowlist, and token injection host recognition.

GITHUB_SERVER_URL=https://github.example.com
GITHUB_API_URL

Base URL of the GitHub (or GHES) REST API for your own repositories. Default: https://api.github.com; on GHES this is typically https://<host>/api/v3.

GITHUB_API_URL=https://github.example.com/api/v3
ATMOS_TOOLCHAIN_GITHUB_URL

Base URL used for toolchain release assets and source archives (github_release and github_archive tool types). Default: https://github.com. Independent of GITHUB_SERVER_URL.

ATMOS_TOOLCHAIN_GITHUB_API_URL

Base URL used for toolchain repository API calls (e.g. fetching a tool's available versions). Default: https://api.github.com. Independent of GITHUB_API_URL.

ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL

Base URL of the aqua-registry raw content mirror (serves registry.yaml and per-package pkgs/<name>/registry.yaml files). Default: https://raw.githubusercontent.com/aquaproj/aqua-registry/main.

ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL=https://releases.corp.example.com/aqua-registry/main
note

The bare owner/repo and literal github.com/owner/repo shorthand forms (imports, vendoring, atmos git clone, AI skill sources, etc.) always resolve to public github.com — a bare hostname can't be distinguished from a relative path, so shorthand detection can't safely guess a GHES host from either form. On GHES, write the full URL instead (e.g. https://github.example.com/owner/repo), with one exception: AI skill sources also accept the actual configured GHES host without a scheme (github.example.com/owner/repo), since a skill source is always a repository reference, never a local path. Imports and vendor manifests need the explicit scheme even for the real GHES host. atmos git clone has no shorthand form at all (on github.com or GHES); it always needs a full URI (HTTPS, SCP-style, or go-getter syntax).

Token scoping

Your GitHub token (ATMOS_GITHUB_TOKEN, GITHUB_TOKEN, --github-token, or gh auth token) is only ever sent to an endpoint under two conditions:

  • The request's actual destination is https. GITHUB_SERVER_URL / GITHUB_API_URL and the ATMOS_TOOLCHAIN_* variables above may resolve to a plain http:// endpoint (this is only expected in local testing); Atmos never attaches the token to a request against a non-https destination, since doing so would send it over the network in cleartext. This is re-checked against the request that is actually about to go out on the wire, not just the URL you configured: an HTTPS endpoint that redirects down to plain http:// on the same host never receives the token on that redirected request either.
  • The request's actual destination belongs to an approved host. For your own repositories (the CI provider, imports/vendoring, the pkg/github API client, and the artifact/cache backends), the approved hosts are GITHUB_SERVER_URL's server, API, and upload hosts. Your token is resolved without regard to host, so it is also treated as scoped to GITHUB_SERVER_URL's host for the toolchain installer and the aqua-registry client: it is forwarded to ATMOS_TOOLCHAIN_GITHUB_URL / ATMOS_TOOLCHAIN_GITHUB_API_URL only when both resolve to that same host as GITHUB_SERVER_URL / GITHUB_API_URL. By default the toolchain endpoints point at public github.com, so on a GHES instance the toolchain fetches proceed unauthenticated unless you explicitly point ATMOS_TOOLCHAIN_GITHUB_URL / ATMOS_TOOLCHAIN_GITHUB_API_URL at your own GHES host too. This host check, like the https check above, is re-evaluated against every request Atmos actually sends -- including every hop of an automatic redirect -- so a redirect to an unapproved host (e.g. GitHub's own pre-signed, unauthenticated blob-storage redirect for an artifact download) never carries the token along, even when that redirect target is itself https.

Both rules apply independently everywhere Atmos builds an authenticated GitHub request or client (the CI provider, imports/vendoring, the pkg/github API client, the artifact/cache backends, the toolchain installer, and the aqua-registry client).

AI Integration​

ATMOS_AI

Enable AI-powered analysis of command output. When true, command output is sent to the configured AI provider for analysis. Equivalent to the --ai flag. Requires AI configuration in atmos.yaml.

  • Example: ATMOS_AI=true atmos terraform plan vpc -s prod
ATMOS_SKILL

Specify one or more AI skills for domain-specific analysis context (comma-separated). Equivalent to the --skill flag. Requires ATMOS_AI=true or --ai flag. Each skill's system prompt is prepended to the AI analysis for deeper, domain-aware insights.

  • Example: ATMOS_AI=true ATMOS_SKILL=atmos-terraform,atmos-stacks atmos terraform plan vpc -s prod
ANTHROPIC_API_KEY / ATMOS_ANTHROPIC_API_KEY

API key for the Anthropic Claude AI provider.

OPENAI_API_KEY / ATMOS_OPENAI_API_KEY

API key for the OpenAI GPT AI provider.

GEMINI_API_KEY / ATMOS_GEMINI_API_KEY

API key for the Google Gemini AI provider.

XAI_API_KEY / ATMOS_XAI_API_KEY

API key for the xAI Grok AI provider.

ATMOS_AI_SEND_CONTEXT

Control whether stack configurations are sent to the AI provider for context-aware answers. Default: false.

ATMOS_AI_MCP

Specify which MCP servers to use (comma-separated). Skips automatic server routing and starts only the specified servers. Equivalent to the --mcp flag on atmos ai ask, atmos ai chat, and atmos ai exec.

  • Example: ATMOS_AI_MCP=aws-iam,aws-billing atmos ai ask "List admin roles and their costs"
ATMOS_AI_INCLUDE

Add glob patterns to include in AI context (comma-separated). Equivalent to the --include flag.

  • Example: ATMOS_AI_INCLUDE="stacks/**/*.yaml" atmos ai ask "Describe our stacks"
ATMOS_AI_EXCLUDE

Add glob patterns to exclude from AI context (comma-separated). Equivalent to the --exclude flag.

  • Example: ATMOS_AI_EXCLUDE="**/secrets/**" atmos ai ask "Analyze our config"
ATMOS_AI_NO_AUTO_CONTEXT

Disable automatic context discovery. Equivalent to the --no-auto-context flag. Default: false.

ATMOS_AI_NO_TOOLS

Disable tool execution for faster, simpler queries. Equivalent to the --no-tools flag. Default: false.

ATMOS_AI_FORMAT

Output format for atmos ai exec: text, json, or markdown. Equivalent to the --format flag. Default: text.

ATMOS_AI_OUTPUT

Output file path for atmos ai exec. Equivalent to the --output flag. Default: stdout.

ATMOS_AI_CONTEXT

Include stack context in the prompt for atmos ai exec. Equivalent to the --context flag. Default: false.

ATMOS_AI_PROVIDER

Override AI provider for atmos ai exec (e.g., anthropic, openai, gemini). Equivalent to the --provider flag.

ATMOS_AI_SESSION

Session ID for conversation context in atmos ai exec and atmos ai chat. Equivalent to the --session flag.

Processing Flags​

ATMOS_PROCESS_TEMPLATES

Enable/disable Go template processing in Atmos manifests.

ATMOS_PROCESS_FUNCTIONS

Enable/disable YAML function processing in Atmos manifests.

ATMOS_SKIP

Skip processing specific Atmos YAML functions (comma-separated).

Terraform Integration​

ATMOS_SKIP_INIT

Skip terraform init before running commands.

ATMOS_INIT_PASS_VARS

Pass the generated varfile to terraform init.

ATMOS_APPEND_USER_AGENT

Customize the User-Agent string sent with Terraform requests.

ATMOS_AUTO_GENERATE_BACKEND_FILE

Override the auto_generate_backend_file setting from atmos.yaml.

ATMOS_INIT_RUN_RECONFIGURE

Override the init_run_reconfigure setting from atmos.yaml. Deprecated in favor of ATMOS_INIT_RECONFIGURE.

ATMOS_INIT_MODE

Override the --init-mode flag / components.terraform.init.mode setting: auto (default), always, or never.

ATMOS_INIT_RECONFIGURE

Override the --init-reconfigure flag / components.terraform.init.reconfigure setting: auto (default), always, or never.

ATMOS_INIT_UPGRADE

Override the --init-upgrade flag / components.terraform.init.upgrade setting: auto (default), always, or never.

ATMOS_TERRAFORM_VERIFY_PLAN

Set to true to force planfile drift verification (fail on drift) on atmos terraform deploy, equivalent to --verify-plan. Set to false to disable verification (equivalent to --verify-plan=false), overriding config and the CI default. See Planfile drift verification.

Atmos Pro​

ATMOS_PRO_BASE_URL

Atmos Pro API base URL.

ATMOS_PRO_ENDPOINT

Atmos Pro API endpoint.

ATMOS_PRO_WORKSPACE_ID

Atmos Pro workspace identifier. Not a secret.

ATMOS_PRO_TOKEN

Bearer token obtained via OIDC token exchange (advanced). See Pro authentication.

ATMOS_UPLOAD_STATUS

Upload plan status to Atmos Pro after Terraform commands.

Telemetry​

ATMOS_TELEMETRY_ENABLED

Enable anonymous telemetry reporting. Default: true.

ATMOS_TELEMETRY_TOKEN

Telemetry authentication token.

ATMOS_TELEMETRY_ENDPOINT

Custom telemetry endpoint URL.

Experimental Features​

ATMOS_EXPERIMENTAL

Control experimental command behavior. Options: silence, disable, warn (default), error.

Toolchain​

ATMOS_TOOL_VERSIONS

Path to a tool-versions file for version pinning.

ATMOS_TOOLCHAIN_PATH

Directory where Atmos installs managed tools.

XDG Base Directories​

ATMOS_XDG_CACHE_HOME / XDG_CACHE_HOME

Override the cache directory. Default: ~/.cache.

ATMOS_XDG_DATA_HOME / XDG_DATA_HOME

Override the data directory. Default: ~/.local/share.

ATMOS_XDG_CONFIG_HOME / XDG_CONFIG_HOME

Override the config directory. Default: ~/.config.

Git Operations​

ATMOS_REPO_PATH

Path to the cloned target repository for describe affected.

ATMOS_REF

Git reference for comparison in describe affected.

ATMOS_SHA

Git commit SHA for comparison in describe affected.

ATMOS_SSH_KEY

Path to SSH private key for Git operations.

ATMOS_SSH_KEY_PASSWORD

SSH key encryption password.

ATMOS_CLONE_TARGET_REF

Clone target Git reference for comparison operations.

ATMOS_INCLUDE_DEPENDENTS

Include dependent components in describe affected output.

Context Variables​

Some commands spawn interactive shells with environment variables set to provide context. These are set by Atmos, not by users:

ATMOS_COMPONENT
The name of the active component.
ATMOS_SHELL_WORKING_DIR
The directory from which native commands should be run.
ATMOS_SHLVL
The depth of Atmos shell nesting. When present, indicates shell was spawned by Atmos.
ATMOS_STACK
The name of the active stack.
ATMOS_TERRAFORM_WORKSPACE
The name of the Terraform workspace in which Terraform commands should be run.
PS1
When a custom shell prompt has been configured, the prompt is set via PS1.
TF_CLI_ARGS_*
Terraform CLI arguments to be passed to Terraform commands.

See Also​