# Environment Variables

import Intro from '@site/src/components/Intro'

<Intro>
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.
</Intro>

## Configuration Variables

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

<dl>
  <dt>`ATMOS_CLI_CONFIG_PATH`</dt>
  <dd>
    Where to find `atmos.yaml`. Path to a folder where `atmos.yaml` CLI config file is located (e.g. `/config`).
  </dd>

  <dt>`ATMOS_CONFIG`</dt>
  <dd>
    Paths to specific configuration files (comma-separated). Equivalent to `--config`.
  </dd>

  <dt>`ATMOS_CONFIG_PATH`</dt>
  <dd>
    Paths to search for Atmos configuration (comma-separated). Equivalent to `--config-path`.
  </dd>

  <dt>`ATMOS_PROFILE`</dt>
  <dd>
    Activate configuration profiles (comma-separated). Equivalent to the `--profile` flag.
  </dd>

  <dt>`ATMOS_BASE_PATH`</dt>
  <dd>
    Base path to `components` and `stacks` folders.

    - **YAML Path:** `base_path`
  </dd>

  <dt>`ATMOS_CHDIR`</dt>
  <dd>
    Change the working directory before executing any command. Equivalent to `--chdir`.
  </dd>

  <dt>`ATMOS_VENDOR_BASE_PATH`</dt>
  <dd>
    Path to vendor configuration file or directory containing vendor files.

    - **YAML Path:** `vendor.base_path`
  </dd>
</dl>

## Version Management

<dl>
  <dt>`ATMOS_USE_VERSION`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_VERSION`</dt>
  <dd>
    Convenience alias for `ATMOS_USE_VERSION`.
  </dd>

  <dt>`ATMOS_VERSION_ENFORCEMENT`</dt>
  <dd>
    Version constraint enforcement mode. Controls behavior when version constraints are defined in `atmos.yaml`.
  </dd>
</dl>

## Terminal and Output Variables

<dl>
  <dt>`ATMOS_NO_COLOR`</dt>
  <dd>
    Disable colored output. Equivalent to `--no-color`.
  </dd>

  <dt>`NO_COLOR`</dt>
  <dd>
    Standard convention to disable colored output. Recognized alongside `ATMOS_NO_COLOR`.
  </dd>

  <dt>`ATMOS_FORCE_COLOR`</dt>
  <dd>
    Force TrueColor output even when terminal detection says otherwise. Equivalent to `--force-color`.
  </dd>

  <dt>`ATMOS_FORCE_TTY`</dt>
  <dd>
    Force TTY mode for terminal output. Equivalent to `--force-tty`.
  </dd>

  <dt>`COLUMNS`</dt>
  <dd>
    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.
  </dd>

  <dt>`ATMOS_REDIRECT_STDERR`</dt>
  <dd>
    Redirect stderr to a file. Equivalent to `--redirect-stderr`.
  </dd>
</dl>

## Component Variables

<dl>
  <dt>`ATMOS_COMPONENTS_TERRAFORM_COMMAND`</dt>
  <dd>
    The executable to be called by `atmos` when running Terraform commands.

    - **YAML Path:** `components.terraform.command`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_BASE_PATH`</dt>
  <dd>
    Base path to Terraform components.

    - **YAML Path:** `components.terraform.base_path`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_APPLY_AUTO_APPROVE`</dt>
  <dd>
    If set to `true`, auto-approve Terraform apply.

    - **YAML Path:** `components.terraform.apply_auto_approve`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_DEPLOY_RUN_INIT`</dt>
  <dd>
    Run `terraform init` when executing `atmos terraform deploy` command.

    - **YAML Path:** `components.terraform.deploy_run_init`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_INIT_RUN_RECONFIGURE`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_INIT_MODE`</dt>
  <dd>
    Controls when Atmos runs `terraform init` automatically: `auto` (default, skip when nothing relevant changed), `always`, or `never`.

    - **YAML Path:** `components.terraform.init.mode`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_INIT_RECONFIGURE`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_INIT_UPGRADE`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_INIT_PASS_VARS`</dt>
  <dd>
    Pass the generated varfile to `terraform init` using the `--var-file` flag.

    - **YAML Path:** `components.terraform.init.pass_vars`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_PLAN_SKIP_PLANFILE`</dt>
  <dd>
    Skip writing the plan to a file by not passing the `-out` flag.

    - **YAML Path:** `components.terraform.plan.skip_planfile`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_AUTO_GENERATE_BACKEND_FILE`</dt>
  <dd>
    If set to `true`, auto-generate Terraform backend config files.

    - **YAML Path:** `components.terraform.auto_generate_backend_file`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_PLUGIN_CACHE`</dt>
  <dd>
    If set to `true`, enable Terraform provider plugin caching.

    - **YAML Path:** `components.terraform.plugin_cache`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_PLUGIN_CACHE_DIR`</dt>
  <dd>
    Custom directory for Terraform provider plugin cache. If not set, uses the XDG cache directory.

    - **YAML Path:** `components.terraform.plugin_cache_dir`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_CACHE_ENABLED`</dt>
  <dd>
    If set to `true`, enable the Terraform registry cache proxy for provider and module registry traffic.

    - **YAML Path:** `components.terraform.cache.enabled`
    - **Default:** `false`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_CACHE_LOCATION`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_AUTO_PROVISION_WORKDIR_FOR_OUTPUTS`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK_TIMEOUT`</dt>
  <dd>
    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](/cli/configuration/components/terraform#flags).

    - **YAML Path:** `components.terraform.flags.lock_timeout`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_FLAGS_LOCK`</dt>
  <dd>
    Default value for terraform's `-lock` flag.

    - **YAML Path:** `components.terraform.flags.lock`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_FLAGS_PARALLELISM`</dt>
  <dd>
    Default value for terraform's `-parallelism` flag.

    - **YAML Path:** `components.terraform.flags.parallelism`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_FLAGS_REFRESH`</dt>
  <dd>
    Default value for terraform's `-refresh` flag.

    - **YAML Path:** `components.terraform.flags.refresh`
  </dd>

  <dt>`ATMOS_COMPONENTS_TERRAFORM_FLAGS_COMPACT_WARNINGS`</dt>
  <dd>
    Default value for terraform's `-compact-warnings` flag.

    - **YAML Path:** `components.terraform.flags.compact_warnings`
    - **Default:** `false`
  </dd>

  <dt>`ATMOS_COMPONENTS_HELMFILE_COMMAND`</dt>
  <dd>
    The executable to be called by `atmos` when running Helmfile commands.

    - **YAML Path:** `components.helmfile.command`
  </dd>

  <dt>`ATMOS_COMPONENTS_HELMFILE_BASE_PATH`</dt>
  <dd>
    Path to helmfile components.

    - **YAML Path:** `components.helmfile.base_path`
  </dd>

  <dt>`ATMOS_COMPONENTS_HELMFILE_USE_EKS`</dt>
  <dd>
    If set to `true`, download `kubeconfig` from EKS before executing `atmos helmfile` commands.

    - **YAML Path:** `components.helmfile.use_eks`
  </dd>

  <dt>`ATMOS_COMPONENTS_HELMFILE_KUBECONFIG_PATH`</dt>
  <dd>
    Path to write the `kubeconfig` file.

    - **YAML Path:** `components.helmfile.kubeconfig_path`
  </dd>

  <dt>`ATMOS_COMPONENTS_HELMFILE_HELM_AWS_PROFILE_PATTERN`</dt>
  <dd>
    Pattern for AWS profile to use when executing `atmos helmfile` commands.

    - **YAML Path:** `components.helmfile.helm_aws_profile_pattern`
  </dd>

  <dt>`ATMOS_COMPONENTS_HELMFILE_CLUSTER_NAME_PATTERN`</dt>
  <dd>
    Pattern for EKS cluster name to use when executing `atmos helmfile` commands.

    - **YAML Path:** `components.helmfile.cluster_name_pattern`
  </dd>
</dl>

## Stack Variables

<dl>
  <dt>`ATMOS_STACKS_BASE_PATH`</dt>
  <dd>
    Base path to Atmos stack manifests.

    - **YAML Path:** `stacks.base_path`
  </dd>

  <dt>`ATMOS_STACKS_INCLUDED_PATHS`</dt>
  <dd>
    List of paths to use as top-level stack manifests.

    - **YAML Path:** `stacks.included_paths`
  </dd>

  <dt>`ATMOS_STACKS_EXCLUDED_PATHS`</dt>
  <dd>
    List of paths to not consider as top-level stacks.

    - **YAML Path:** `stacks.excluded_paths`
  </dd>

  <dt>`ATMOS_STACKS_NAME_PATTERN`</dt>
  <dd>
    Stack name pattern to use as Atmos stack names.

    - **YAML Path:** `stacks.name_pattern`
  </dd>

  <dt>`ATMOS_STACKS_NAME_TEMPLATE`</dt>
  <dd>
    Stack name Golang template to use as Atmos stack names.

    - **YAML Path:** `stacks.name_template`
  </dd>
</dl>

## Workflow and Schema Variables

<dl>
  <dt>`ATMOS_WORKFLOWS_BASE_PATH`</dt>
  <dd>
    Base path to Atmos workflows.

    - **YAML Path:** `workflows.base_path`
  </dd>

  <dt>`ATMOS_SCHEMAS_JSONSCHEMA_BASE_PATH`</dt>
  <dd>
    Base path to JSON schemas for component validation.

    - **YAML Path:** `schemas.jsonschema.base_path`
  </dd>

  <dt>`ATMOS_SCHEMAS_OPA_BASE_PATH`</dt>
  <dd>
    Base path to OPA policies for component validation.

    - **YAML Path:** `schemas.opa.base_path`
  </dd>

  <dt>`ATMOS_SCHEMAS_ATMOS_MANIFEST`</dt>
  <dd>
    Path to JSON Schema to validate Atmos stack manifests.

    - **YAML Path:** `schemas.atmos.manifest`
  </dd>
</dl>

## Logging and Profiling Variables

<dl>
  <dt>`ATMOS_LOGS_FILE`</dt>
  <dd>
    The file to write Atmos logs to (`/dev/stdout`, `/dev/stderr`, `/dev/null`, or a file path).

    - **YAML Path:** `logs.file`
  </dd>

  <dt>`ATMOS_LOGS_LEVEL`</dt>
  <dd>
    Logs level: `Trace`, `Debug`, `Info`, `Warning`, `Off`.

    - **YAML Path:** `logs.level`
  </dd>

  <dt>`ATMOS_PROFILER_ENABLED`</dt>
  <dd>
    Enable or disable the pprof HTTP profiling server.

    - **YAML Path:** `profiler.enabled`
  </dd>

  <dt>`ATMOS_PROFILER_HOST`</dt>
  <dd>
    Host address for the profiling server.

    - **YAML Path:** `profiler.host`
  </dd>

  <dt>`ATMOS_PROFILER_PORT`</dt>
  <dd>
    Port for the profiling server.

    - **YAML Path:** `profiler.port`
  </dd>

  <dt>`ATMOS_PROFILE_FILE`</dt>
  <dd>
    Write profiling data to the specified file.

    - **YAML Path:** `profiler.file`
  </dd>

  <dt>`ATMOS_PROFILE_TYPE`</dt>
  <dd>
    Type of profile to collect: `cpu`, `heap`, `allocs`, `goroutine`, `block`, `mutex`, `threadcreate`, `trace`.

    - **YAML Path:** `profiler.profile_type`
  </dd>
</dl>

## Settings Variables

<dl>
  <dt>`ATMOS_SETTINGS_LIST_MERGE_STRATEGY`</dt>
  <dd>
    Specifies how lists are merged: `replace`, `append`, `merge`.

    - **YAML Path:** `settings.list_merge_strategy`
  </dd>

  <dt>`ATMOS_VERSION_CHECK_ENABLED`</dt>
  <dd>
    Enable/disable Atmos version checks for updates.

    - **YAML Path:** `version.check.enabled`
  </dd>
</dl>

## Authentication and Token Injection

<dl>
  <dt>`GITHUB_TOKEN` / `ATMOS_GITHUB_TOKEN`</dt>
  <dd>
    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).
  </dd>

  <dt>`ATMOS_PRO_GITHUB_TOKEN`</dt>
  <dd>
    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).
  </dd>

  <dt>`ATMOS_INJECT_GITHUB_TOKEN`</dt>
  <dd>
    Inject the GitHub token into component environments. Default: `true`. Set to `false` to prevent token injection.
  </dd>

  <dt>`ATMOS_GITHUB_CLI`</dt>
  <dd>
    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).
  </dd>

  <dt>`GITHUB_USERNAME` / `GITHUB_ACTOR` / `ATMOS_GITHUB_USERNAME`</dt>
  <dd>
    GitHub username for OCI registry authentication to ghcr.io. `GITHUB_ACTOR` is automatically set in GitHub Actions.

    - **YAML Path:** `settings.github_username`
  </dd>

  <dt>`GITLAB_TOKEN` / `ATMOS_GITLAB_TOKEN`</dt>
  <dd>
    GitLab token for private module downloads.
  </dd>

  <dt>`ATMOS_INJECT_GITLAB_TOKEN`</dt>
  <dd>
    Inject the GitLab token into component environments.
  </dd>

  <dt>`BITBUCKET_TOKEN` / `ATMOS_BITBUCKET_TOKEN`</dt>
  <dd>
    App password for Bitbucket API requests and private module downloads.
  </dd>

  <dt>`ATMOS_INJECT_BITBUCKET_TOKEN`</dt>
  <dd>
    Inject the Bitbucket token into component environments.
  </dd>

  <dt>`BITBUCKET_USERNAME`</dt>
  <dd>
    Username for Bitbucket authentication. Bitbucket requires a valid username and does not accept dummy values like `x-access-token`.
  </dd>
</dl>

## GitHub Enterprise Server (GHES) {#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.

<dl>
  <dt>`GITHUB_SERVER_URL`</dt>
  <dd>
    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.

    ```shell
    GITHUB_SERVER_URL=https://github.example.com
    ```
  </dd>

  <dt>`GITHUB_API_URL`</dt>
  <dd>
    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`.

    ```shell
    GITHUB_API_URL=https://github.example.com/api/v3
    ```
  </dd>

  <dt>`ATMOS_TOOLCHAIN_GITHUB_URL`</dt>
  <dd>
    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`.
  </dd>

  <dt>`ATMOS_TOOLCHAIN_GITHUB_API_URL`</dt>
  <dd>
    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`.
  </dd>

  <dt>`ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL`</dt>
  <dd>
    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`.

    ```shell
    ATMOS_TOOLCHAIN_AQUA_REGISTRY_URL=https://releases.corp.example.com/aqua-registry/main
    ```
  </dd>
</dl>

:::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).
:::

:::caution 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

<dl>
  <dt>`ATMOS_AI`</dt>
  <dd>
    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`
  </dd>

  <dt>`ATMOS_SKILL`</dt>
  <dd>
    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`
  </dd>

  <dt>`ANTHROPIC_API_KEY` / `ATMOS_ANTHROPIC_API_KEY`</dt>
  <dd>
    API key for the Anthropic Claude AI provider.
  </dd>

  <dt>`OPENAI_API_KEY` / `ATMOS_OPENAI_API_KEY`</dt>
  <dd>
    API key for the OpenAI GPT AI provider.
  </dd>

  <dt>`GEMINI_API_KEY` / `ATMOS_GEMINI_API_KEY`</dt>
  <dd>
    API key for the Google Gemini AI provider.
  </dd>

  <dt>`XAI_API_KEY` / `ATMOS_XAI_API_KEY`</dt>
  <dd>
    API key for the xAI Grok AI provider.
  </dd>

  <dt>`ATMOS_AI_SEND_CONTEXT`</dt>
  <dd>
    Control whether stack configurations are sent to the AI provider for context-aware answers. Default: `false`.
  </dd>

  <dt>`ATMOS_AI_MCP`</dt>
  <dd>
    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"`
  </dd>

  <dt>`ATMOS_AI_INCLUDE`</dt>
  <dd>
    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"`
  </dd>

  <dt>`ATMOS_AI_EXCLUDE`</dt>
  <dd>
    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"`
  </dd>

  <dt>`ATMOS_AI_NO_AUTO_CONTEXT`</dt>
  <dd>
    Disable automatic context discovery. Equivalent to the `--no-auto-context` flag. Default: `false`.
  </dd>

  <dt>`ATMOS_AI_NO_TOOLS`</dt>
  <dd>
    Disable tool execution for faster, simpler queries. Equivalent to the `--no-tools` flag. Default: `false`.
  </dd>

  <dt>`ATMOS_AI_FORMAT`</dt>
  <dd>
    Output format for `atmos ai exec`: `text`, `json`, or `markdown`. Equivalent to the `--format` flag. Default: `text`.
  </dd>

  <dt>`ATMOS_AI_OUTPUT`</dt>
  <dd>
    Output file path for `atmos ai exec`. Equivalent to the `--output` flag. Default: stdout.
  </dd>

  <dt>`ATMOS_AI_CONTEXT`</dt>
  <dd>
    Include stack context in the prompt for `atmos ai exec`. Equivalent to the `--context` flag. Default: `false`.
  </dd>

  <dt>`ATMOS_AI_PROVIDER`</dt>
  <dd>
    Override AI provider for `atmos ai exec` (e.g., `anthropic`, `openai`, `gemini`). Equivalent to the `--provider` flag.
  </dd>

  <dt>`ATMOS_AI_SESSION`</dt>
  <dd>
    Session ID for conversation context in `atmos ai exec` and `atmos ai chat`. Equivalent to the `--session` flag.
  </dd>
</dl>

## Processing Flags

<dl>
  <dt>`ATMOS_PROCESS_TEMPLATES`</dt>
  <dd>
    Enable/disable Go template processing in Atmos manifests.
  </dd>

  <dt>`ATMOS_PROCESS_FUNCTIONS`</dt>
  <dd>
    Enable/disable YAML function processing in Atmos manifests.
  </dd>

  <dt>`ATMOS_SKIP`</dt>
  <dd>
    Skip processing specific Atmos YAML functions (comma-separated).
  </dd>
</dl>

## Terraform Integration

<dl>
  <dt>`ATMOS_SKIP_INIT`</dt>
  <dd>
    Skip `terraform init` before running commands.
  </dd>

  <dt>`ATMOS_INIT_PASS_VARS`</dt>
  <dd>
    Pass the generated varfile to `terraform init`.
  </dd>

  <dt>`ATMOS_APPEND_USER_AGENT`</dt>
  <dd>
    Customize the User-Agent string sent with Terraform requests.
  </dd>

  <dt>`ATMOS_AUTO_GENERATE_BACKEND_FILE`</dt>
  <dd>
    Override the `auto_generate_backend_file` setting from `atmos.yaml`.
  </dd>

  <dt>`ATMOS_INIT_RUN_RECONFIGURE`</dt>
  <dd>
    Override the `init_run_reconfigure` setting from `atmos.yaml`. Deprecated in favor of `ATMOS_INIT_RECONFIGURE`.
  </dd>

  <dt>`ATMOS_INIT_MODE`</dt>
  <dd>
    Override the `--init-mode` flag / `components.terraform.init.mode` setting: `auto` (default), `always`, or `never`.
  </dd>

  <dt>`ATMOS_INIT_RECONFIGURE`</dt>
  <dd>
    Override the `--init-reconfigure` flag / `components.terraform.init.reconfigure` setting: `auto` (default), `always`, or `never`.
  </dd>

  <dt>`ATMOS_INIT_UPGRADE`</dt>
  <dd>
    Override the `--init-upgrade` flag / `components.terraform.init.upgrade` setting: `auto` (default), `always`, or `never`.
  </dd>

  <dt>`ATMOS_TERRAFORM_VERIFY_PLAN`</dt>
  <dd>
    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](/components/terraform/planfiles#drift-verification).
  </dd>
</dl>

## Atmos Pro

<dl>
  <dt>`ATMOS_PRO_BASE_URL`</dt>
  <dd>
    Atmos Pro API base URL.
  </dd>

  <dt>`ATMOS_PRO_ENDPOINT`</dt>
  <dd>
    Atmos Pro API endpoint.
  </dd>

  <dt>`ATMOS_PRO_WORKSPACE_ID`</dt>
  <dd>
    Atmos Pro workspace identifier. Not a secret.
  </dd>

  <dt>`ATMOS_PRO_TOKEN`</dt>
  <dd>
    Bearer token obtained via OIDC token exchange (advanced). See [Pro authentication](/cli/configuration/settings/pro#authentication).
  </dd>

  <dt>`ATMOS_UPLOAD_STATUS`</dt>
  <dd>
    Upload plan status to Atmos Pro after Terraform commands.
  </dd>
</dl>

## Telemetry

<dl>
  <dt>`ATMOS_TELEMETRY_ENABLED`</dt>
  <dd>
    Enable anonymous telemetry reporting. Default: `true`.
  </dd>

  <dt>`ATMOS_TELEMETRY_TOKEN`</dt>
  <dd>
    Telemetry authentication token.
  </dd>

  <dt>`ATMOS_TELEMETRY_ENDPOINT`</dt>
  <dd>
    Custom telemetry endpoint URL.
  </dd>
</dl>

## Experimental Features

<dl>
  <dt>`ATMOS_EXPERIMENTAL`</dt>
  <dd>
    Control experimental command behavior. Options: `silence`, `disable`, `warn` (default), `error`.
  </dd>
</dl>

## Toolchain

<dl>
  <dt>`ATMOS_TOOL_VERSIONS`</dt>
  <dd>
    Path to a tool-versions file for version pinning.
  </dd>

  <dt>`ATMOS_TOOLCHAIN_PATH`</dt>
  <dd>
    Directory where Atmos installs managed tools.
  </dd>
</dl>

## XDG Base Directories

<dl>
  <dt>`ATMOS_XDG_CACHE_HOME` / `XDG_CACHE_HOME`</dt>
  <dd>
    Override the cache directory. Default: `~/.cache`.
  </dd>

  <dt>`ATMOS_XDG_DATA_HOME` / `XDG_DATA_HOME`</dt>
  <dd>
    Override the data directory. Default: `~/.local/share`.
  </dd>

  <dt>`ATMOS_XDG_CONFIG_HOME` / `XDG_CONFIG_HOME`</dt>
  <dd>
    Override the config directory. Default: `~/.config`.
  </dd>
</dl>

## Git Operations

<dl>
  <dt>`ATMOS_REPO_PATH`</dt>
  <dd>
    Path to the cloned target repository for `describe affected`.
  </dd>

  <dt>`ATMOS_REF`</dt>
  <dd>
    Git reference for comparison in `describe affected`.
  </dd>

  <dt>`ATMOS_SHA`</dt>
  <dd>
    Git commit SHA for comparison in `describe affected`.
  </dd>

  <dt>`ATMOS_SSH_KEY`</dt>
  <dd>
    Path to SSH private key for Git operations.
  </dd>

  <dt>`ATMOS_SSH_KEY_PASSWORD`</dt>
  <dd>
    SSH key encryption password.
  </dd>

  <dt>`ATMOS_CLONE_TARGET_REF`</dt>
  <dd>
    Clone target Git reference for comparison operations.
  </dd>

  <dt>`ATMOS_INCLUDE_DEPENDENTS`</dt>
  <dd>
    Include dependent components in `describe affected` output.
  </dd>
</dl>

## Context Variables

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

<dl>
  <dt>`ATMOS_COMPONENT`</dt>
  <dd>The name of the active component.</dd>

  <dt>`ATMOS_SHELL_WORKING_DIR`</dt>
  <dd>The directory from which native commands should be run.</dd>

  <dt>`ATMOS_SHLVL`</dt>
  <dd>The depth of Atmos shell nesting. When present, indicates shell was spawned by Atmos.</dd>

  <dt>`ATMOS_STACK`</dt>
  <dd>The name of the active stack.</dd>

  <dt>`ATMOS_TERRAFORM_WORKSPACE`</dt>
  <dd>The name of the Terraform workspace in which Terraform commands should be run.</dd>

  <dt>`PS1`</dt>
  <dd>When a custom shell prompt has been configured, the prompt is set via `PS1`.</dd>

  <dt>`TF_CLI_ARGS_*`</dt>
  <dd>Terraform CLI arguments to be passed to Terraform commands.</dd>
</dl>

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