# 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>
    Any nonempty value disables color in Atmos logs and UI, including `NO_COLOR=0`.
    Takes precedence over `CLICOLOR`, `CLICOLOR_FORCE`, and `--force-color`.
    An empty value is treated as unset.
  </dd>

  <dt>`CLICOLOR`</dt>
  <dd>
    Controls automatic color without forcing it. `CLICOLOR=0` disables color unless
    explicitly forced; `CLICOLOR=1` (or another nonzero value) permits color when
    supported by the terminal or CI environment. It does not force color into pipes
    or files. An empty value leaves automatic detection unchanged.
    If both `NO_COLOR` and `CLICOLOR=1` are set, nonempty `NO_COLOR` wins and output
    stays plain. See [color precedence](/cli/configuration/settings/terminal#color-configuration-precedence).
  </dd>

  <dt>`CLICOLOR_FORCE`</dt>
  <dd>
    Use `CLICOLOR_FORCE=1` to force color even in pipes or files, overriding
    `CLICOLOR=0`. Nonempty `NO_COLOR` and `--no-color` still disable 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_MOCKS_MODE`</dt>
  <dd>
    Controls how [component mocks](/stacks/components/mocks) are used when `--use-mocks` is passed: `fallback` (real state wins, mocks fill gaps) or `always` (mocks only). Defaults to `fallback`, or `always` for projects pinned to a [config edition](/cli/configuration/edition) before 2026-10-01.

    The value is case-insensitive, and an invalid value fails at configuration load for every command.

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

  <dt>`ATMOS_USE_MOCKS`</dt>
  <dd>
    Turns on [component mocks](/stacks/components/mocks) for `atmos terraform plan`, the same as passing `--use-mocks`. Accepts the same values as the flag, case-insensitively: a false boolean (`false`, `0`, `f`) or an empty value is off, a true boolean (`true`, `1`, `t`) uses the mode from `components.terraform.mocks.mode`, and `fallback` or `always` override it for the run. Any other value is an error. `atmos describe component` does not read this variable; pass `--use-mocks` instead. If this variable is exported, every `atmos terraform` subcommand other than `plan` (for example `apply`, `deploy`, and `destroy`) fails with an error naming it, so unset it before running them.
  </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>

## Policy Variables

<dl>
  <dt><code>ATMOS_POLICY_DIR</code></dt>
  <dd>
    Directory containing <code>atmos/v1</code> <code>Policy</code> documents. No default;
    unset or empty disables directory-based policies. Use an absolute, protected path in CI.
    There is no corresponding <code>atmos.yaml</code> field.
    See <a href="/policies/configuration">Policy Configuration</a> for loading rules and schema.
  </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_COLOR`</dt>
  <dd>
    Enable log color when available: `true` (default) or `false`. Existing force-color
    controls apply when enabled. `--logs-color` overrides this variable; `--no-color`
    and nonempty `NO_COLOR` always disable color.

    - **YAML Path:** `logs.color`
  </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>`ATMOS_AUTH_JUSTIFICATION`</dt>
  <dd>
    Human-readable reason recorded for privileged authentication actions, such as [Azure PIM role activation](/cli/configuration/auth/identities#pim-role-activation). Equivalent to the [`--justification`](/cli/global-flags#authentication-flags) global flag (the flag takes precedence). Auth-level and portable across implementations. Resolution order: `--justification` > `ATMOS_AUTH_JUSTIFICATION` > the identity's `principal.justification` default > interactive prompt.
  </dd>

  <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`. The
    native CI GitHub provider also uses it for PR comments and commit statuses.

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

  <dt>`ATMOS_CI_GITHUB_API_URL`</dt>
  <dd>
    Overrides the GitHub REST API base URL for the native CI GitHub provider only. Takes
    precedence over `GITHUB_API_URL`, which lets you point CI reporting at a different API host
    without changing how imports and vendoring resolve GitHub. The value must be an absolute
    `http(s)` URL; an invalid value fails instead of sending the token to an unintended host.

    ```shell
    ATMOS_CI_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>

## CI Reporting Variables {#ci-reporting}

These variables feed the `generic` CI provider, which Atmos uses when no CI platform is recognized and when
CI mode is forced with the `--ci` flag or `ATMOS_CI=true`. They let a laptop or an unsupported CI platform supply the
facts that GitHub Actions provides on its own. See [CI configuration](/cli/configuration/ci) and the
[`ci` module](/functions/automation/ci).

<dl>
  <dt>`ATMOS_CI_PR`</dt>
  <dd>
    Pull request number (a positive integer). Makes the local comment and check preview target that pull request.
    Nothing is posted outside a recognized CI provider. Without it, the generic provider reports no pull request.
  </dd>

  <dt>`ATMOS_CI_PR_FORK`</dt>
  <dd>
    Whether the pull request head lives in a fork (`true` or `false`). Read only when `ATMOS_CI_PR` is set. It fills
    `ci.context.pr.fork` and never gates anything on the generic provider.
  </dd>

  <dt>`ATMOS_CI_EVENT`</dt>
  <dd>Event name, such as `push` or `pull_request`.</dd>

  <dt>`ATMOS_CI_RUN_ID`</dt>
  <dd>Run or job identifier. Falls back to `CI_JOB_ID`, then `BUILD_ID`.</dd>

  <dt>`ATMOS_CI_RUN_URL`</dt>
  <dd>Link to the run or job. Falls back to `CI_JOB_URL`, then `BUILD_URL`.</dd>

  <dt>`ATMOS_CI_REPOSITORY`</dt>
  <dd>
    Repository in `owner/name` form. Falls back to `CI_PROJECT_PATH`. The `atmos terraform plan --ci` comment preview
    needs it, together with `ATMOS_CI_PR`.
  </dd>

  <dt>`ATMOS_CI_SHA`</dt>
  <dd>Commit SHA. Falls back to `GIT_COMMIT`, `CI_COMMIT_SHA`, `COMMIT_SHA`, then the checked-out commit.</dd>

  <dt>`ATMOS_CI_BRANCH`</dt>
  <dd>Branch name. Falls back to `GIT_BRANCH`, `CI_COMMIT_REF_NAME`, `BRANCH_NAME`, then the checked-out branch.</dd>

  <dt>`ATMOS_CI_ACTOR`</dt>
  <dd>User that triggered the run. Falls back to `CI_COMMIT_AUTHOR`, then `USER`.</dd>

  <dt>`ATMOS_CI_SERVER_URL`</dt>
  <dd>Base URL of the CI server. Falls back to `CI_SERVER_URL`.</dd>

  <dt>`ATMOS_CI_REPOSITORY_URL`</dt>
  <dd>Clone URL of the repository. Falls back to `CI_REPOSITORY_URL`, then `GIT_URL`.</dd>

  <dt>`ATMOS_CI_BASE_REF`</dt>
  <dd>Base branch for affected detection and for `ci.base()`.</dd>

  <dt>`ATMOS_CI_OUTPUT`</dt>
  <dd>
    File the generic provider appends step outputs to, in GitHub Actions `key=value` format. Multiline values use the
    heredoc form. Without it, outputs print to stderr.
  </dd>

  <dt>`ATMOS_CI_SUMMARY`</dt>
  <dd>File the generic provider appends job summary Markdown to. Without it, the summary renders on stderr.</dd>

  <dt>`ATMOS_CI_ENV`</dt>
  <dd>
    File the generic provider appends environment exports to, in GitHub Actions `KEY=value` format. Without it,
    `export KEY=value` lines print to stderr, with the value shell-quoted only when it needs quoting.
  </dd>

  <dt>`ATMOS_CI_PATH`</dt>
  <dd>
    File the generic provider appends `PATH` additions to, one directory per line. Without it, an `export PATH=...`
    line prints to stderr.
  </dd>

  <dt>`ATMOS_ALLOW_UNSAFE_FORK_EXECUTION`</dt>
  <dd>
    Sets `ci.allow_unsafe_fork_execution`. It releases both the clone gate of
    [`atmos git clone`](/cli/commands/git/clone#fork-pr-safety-gate) and the posting gate that holds comments, commit
    statuses, environment and `PATH` exports, and SARIF uploads for fork pull requests under the elevated
    `pull_request_target` and `workflow_run` events. **Unsafe**: leave it unset unless a fork-facing workflow has a
    documented reason to bypass the gates.
  </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>

  <dt>`ATMOS_TOOLCHAIN_INSTALL`</dt>
  <dd>
    Controls which tools Atmos installs automatically: `never`, `declared`, `auto`, or `always`.
    Defaults to `auto`, or `declared` for projects pinned to a [config edition](/cli/configuration/edition)
    before 2026-10-09. An invalid value fails at configuration load.
    See [`toolchain.install`](/cli/configuration/toolchain#install).

    - **YAML Path:** `toolchain.install`
  </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>

  <dt>`ATMOS_GIT_HOOK_ARGS`</dt>
  <dd>
    Set by Atmos while a Git hook runs. The arguments Git passed to the hook, joined by single spaces. Shell steps also
    receive them as `"$@"`, which keeps arguments with spaces intact. See [Git hooks](/cli/configuration/git).
  </dd>

  <dt>`ATMOS_GIT_HOOK_STDIN`</dt>
  <dd>
    Set by Atmos while a `pre-push`, `pre-receive`, `post-receive`, `post-rewrite`, `reference-transaction`, or
    `proc-receive` hook runs. The path of a temporary file that holds the data Git piped to the hook. Atmos removes the
    file when the hook ends. The first shell step still receives the same data on standard input.
  </dd>

  <dt>`ATMOS_HOOK_DEPTH`</dt>
  <dd>
    Set by Atmos for the commands a hook runs. It counts how many hooks deep the running command is. A hook that
    runs at depth 8 is allowed; attempting to start a ninth nested hook fails with `hook recursion limit exceeded`,
    naming the hook and its event. This bounds recursion when a hook runs the command it is attached to.
  </dd>

  <dt>`ATMOS_CONFIG_GET_FORMAT`</dt>
  <dd>
    Default for the `--format` flag of [`atmos config get`](/cli/commands/config/config-get): `raw` or `json`.
    Default: `raw`.
  </dd>

  <dt>`ATMOS_STACK_GET_FORMAT`</dt>
  <dd>
    Default for the `--format` flag of [`atmos stack get`](/cli/commands/stack/stack-get): `raw` or `json`.
    Default: `raw`.
  </dd>

  <dt>`ATMOS_STACK_CONFIG_GET_FORMAT`</dt>
  <dd>
    Default for the `--format` flag of [`atmos stack config get`](/cli/commands/stack/config/get): `raw` or `json`.
    Default: `raw`.
  </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