# 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`.
- **`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.
  - **YAML Path:** `components.terraform.init_run_reconfigure`
- **`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_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_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](/cli/configuration/auth#github-sts-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`.

## 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`.

## 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](/cli/configuration/settings/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

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [Global Flags](/cli/global-flags) — Flag reference with environment variable equivalents
- [Environment Variable Injection](/cli/configuration/env) — Configure the `env:` section in `atmos.yaml` to inject variables into tools
- [Stack Environment Variables](/stacks/env) — Component-level environment variables
- [AI Configuration](/cli/configuration/ai) — AI provider setup and configuration
- [Profiles](/cli/configuration/profiles) — Environment-specific configuration overrides
- [Logs](/cli/configuration/logs) — Configure logging
- [Profiler](/cli/configuration/profiler) — Configure performance profiling