CLI Configuration

Use the atmos.yaml configuration file to control the behavior of the Atmos CLI

Everything in the Atmos CLI is configurable. The defaults are established in the atmos.yaml configuration file. The CLI configuration should not be confused with Stack configurations, which have a different schema.

Think of this file as where you bootstrap the settings of your project. If you'll be using Terraform, then this is where you'd specify the command to run (e.g. opentofu), the base path location of the components, and so forth.

Configuration File (atmos.yaml)

Atmos discovers configuration from multiple sources in the following precedence order (highest to lowest priority):

1. Command-line flags (--config, --config-path)
2. Environment variable (ATMOS_CLI_CONFIG_PATH)
3. Profiles (--profile or ATMOS_PROFILE) — Named configuration overrides applied on top of base config
4. Current directory (./atmos.yaml) - CWD only, no parent search
5. Git repository root (repo-root/atmos.yaml) - if in a git repository
6. Parent directory search - walks up from CWD looking for atmos.yaml
7. Home directory (~/.atmos/atmos.yaml)
8. System directory (/usr/local/etc/atmos/atmos.yaml on Linux, %LOCALAPPDATA%/atmos/atmos.yaml on Windows)

Each configuration file discovered is deep-merged with the preceding configurations. Separately, Atmos may also auto-import configuration fragments from .atmos.d/. The git repository root is special: even when atmos.yaml is found elsewhere, Atmos always checks for .atmos.d/ at the repo root to load shared fragments like custom commands.

Profiles are a first-class concept that allow environment-specific configuration overrides. When activated via --profile flag or ATMOS_PROFILE environment variable, profile settings are merged on top of the base configuration. Multiple profiles can be activated and merged left-to-right. See Profiles for complete documentation.

Parent Directory Search

When no atmos.yaml is found in the current directory, Atmos automatically searches parent directories up to the filesystem root. This enables running Atmos from any subdirectory without specifying --config-path.

# Repository structure:
# /repo/
#   atmos.yaml          # ← Found via parent search
#   components/
#     terraform/
#       vpc/            # ← Running from here
#         main.tf

cd /repo/components/terraform/vpc
atmos terraform plan vpc -s prod  # Automatically finds /repo/atmos.yaml

Disabling parent directory search:

Set ATMOS_CLI_CONFIG_PATH to any value (including .) to disable parent directory searching and use only the specified path.

Loading Multiple Configurations

The --config and --config-path flags allow you to load multiple configuration files:

atmos --config /path/to/config1.yaml --config /path/to/config2.yaml \
      --config-path /path/first/config/ --config-path /path/second/config/ ...

Configurations are deep-merged in the order provided, with later configurations overriding earlier ones.

Profiles

Profiles provide named sets of configuration overrides that can be activated at runtime. This is the recommended way to manage environment-specific settings (development, CI/CD, production) without modifying your base configuration.

# Activate a profile via flag
atmos --profile developer terraform plan vpc -s prod

# Activate via environment variable
export ATMOS_PROFILE=ci
atmos terraform apply --auto-approve

# Activate multiple profiles (merged left-to-right)
atmos --profile base,developer,debug describe config

Profiles are discovered from multiple locations:

1. Custom path configured in profiles.base_path
2. .atmos/profiles/ (project-local)
3. ~/.config/atmos/profiles/ (XDG user profiles)
4. profiles/ (project-local)

When multiple profiles are activated, they are merged in order. Later profiles override earlier ones.

For complete documentation on creating and using profiles, see Profiles.

Glob Patterns

Atmos supports POSIX-style Glob patterns for file discovery:

Pattern	Meaning	Example
*	Match any single path segment	stacks/*.yaml
**	Match zero or more path segments (recursive)	stacks/**/*.yaml
?	Match single character	stack?.yaml

Behavior notes:

• .yaml files take priority over .yml with the same base name
• Results are sorted by depth (shallower first), then alphabetically
• Duplicate files are automatically deduplicated

YAML Functions

Atmos extends standard YAML with custom functions that provide powerful tools for dynamic configuration. Use these functions anywhere in your atmos.yaml:

!env

Retrieve environment variables for use in configuration.

base_path: !env ATMOS_BASE_PATH
logs:
  level: !env ATMOS_LOG_LEVEL

See the !env documentation for more details.

!exec

Execute shell scripts and use their output in configuration.

settings:
  account_id: !exec "aws sts get-caller-identity --query Account --output text"

See the !exec documentation for more details.

!include

Include other YAML files into the current configuration. Useful for sharing common settings across multiple configurations.

settings: !include "./common-settings.yaml"

See the !include documentation for more details.

!repo-root

Retrieve the root directory of the Git repository. If the Git root is not found, it will return a default value if specified; otherwise, it returns an error.

base_path: !repo-root

See the !repo-root documentation for more details.

!cwd

Retrieve the current working directory. Useful when you need paths relative to where Atmos is executed from rather than relative to the configuration file.

base_path: !cwd
# or with a relative path
base_path: !cwd ./relative/path

See the !cwd documentation for more details.

Base Path

The base path establishes the root directory for all Atmos paths. When set, component paths, stack paths, workflow paths, and schema paths are resolved relative to it.

base_path: "."

It can also be set using:

• ATMOS_BASE_PATH environment variable
• --base-path command-line argument

It supports both absolute and relative paths.

Path Resolution Semantics

The base_path value determines where Atmos looks for stacks and components. Here's how different values are resolved:

base_path value	Resolves to	Description
"", ~, null, or unset	Git root, fallback to config directory	Smart default with git root discovery
"."	Config file directory	Relative to where atmos.yaml is located
".."	Parent of config file directory	Relative to where atmos.yaml is located
"./foo"	Config file directory + foo	Relative to where atmos.yaml is located
"../foo"	Parent of config directory + foo	Relative to where atmos.yaml is located
"foo"	Git root + foo, fallback to config directory + foo	Simple relative path with search
"/absolute/path"	/absolute/path	Explicit absolute path
!repo-root	Git repository root	Explicit git root tag
!cwd	Current working directory	Explicit CWD tag

Why . and .. are config-file-relative:

Paths in configuration files are relative to where the config file is located, not where you run from. This follows the convention established by other configuration files like tsconfig.json, package.json, and .eslintrc.

For example, if your atmos.yaml is in /repo/config/atmos.yaml and contains:

base_path: ".."  # Resolves to /repo (parent of config directory)

This means you can run atmos from anywhere, and the paths will always resolve correctly relative to where the configuration file is defined.

Need CWD-relative behavior?

If you need paths relative to where Atmos is executed (the current working directory), use the !cwd YAML function:

base_path: !cwd
# or with a relative path
base_path: !cwd ./my/path

Subpath Configuration

If base_path is not provided or is an empty string, the following paths are independent settings (supporting both absolute and relative paths):

• components.terraform.base_path
• components.helmfile.base_path
• stacks.base_path
• workflows.base_path

If base_path is provided, these paths are considered relative to base_path:

• components.terraform.base_path
• components.helmfile.base_path
• stacks.base_path
• workflows.base_path
• schemas.jsonschema.base_path
• schemas.opa.base_path

Git Root Discovery

When using the default configuration and no local atmos.yaml exists in the current directory, Atmos automatically discovers the git repository root and uses it as the base path. This enables running Atmos from any subdirectory, just like Git.

When you run Atmos from a subdirectory:

1. Atmos checks if a local configuration exists in the current directory
2. If no local configuration is found, it detects the git repository root
3. The repository root is used as base_path automatically

Local configuration always takes precedence. If any of these exist in the current directory, git root discovery is skipped:

• atmos.yaml - Main config file
• .atmos.yaml - Hidden config file
• .atmos/ - Config directory
• .atmos.d/ - Default imports directory
• atmos.d/ - Alternate imports directory

Example:

# Repository structure:
# /repo/
#   atmos.yaml
#   components/terraform/vpc/
#     main.tf

# Works from any subdirectory
cd /repo/components/terraform/vpc
atmos terraform plan vpc -s prod  # Automatically uses /repo as base_path

Disabling git root discovery:

export ATMOS_GIT_ROOT_BASEPATH=false

tip

This feature mirrors Git's behavior of finding the repository root from any subdirectory. You no longer need to cd back to the repository root to run Atmos commands.

Automatic Configuration Imports (.atmos.d)

Atmos automatically imports configuration fragments from special directories, enabling modular configuration without explicit import statements.

Supported directory names:

• .atmos.d/ (preferred)
• atmos.d/ (alternate)

Discovery locations (in precedence order, lowest to highest):

1. Git repository root — .atmos.d/ at the repo root is always discovered, even when running from subdirectories
2. Configuration directory — .atmos.d/ next to atmos.yaml (overrides git root)

This means you can place shared custom commands at the repository root and they'll be available from any subdirectory, while still allowing project-specific overrides.

How it works:

1. Atmos recursively discovers all .yaml and .yml files in these directories
2. Files are sorted by directory depth (shallower first), then alphabetically
3. Each file is automatically merged into the configuration
4. Git root .atmos.d is loaded first (lower priority), then config directory .atmos.d (higher priority)
5. Processing occurs after main config merges but before explicit import: entries

Example structure:

repo/                        # Git repository root
├── .atmos.d/
│   └── commands.yaml        # Shared commands available repo-wide
├── atmos.yaml               # Main configuration
├── components/
│   └── terraform/
│       └── vpc/
│           └── main.tf      # ← Can run atmos from here

Running from repo/components/terraform/vpc/:

• Commands from repo/.atmos.d/commands.yaml are automatically discovered
• No need to specify --config-path or change directories

Use cases:

• Custom commands — Drop in command definitions without modifying atmos.yaml
• Repo-wide commands — Define commands at repo root, use from any subdirectory
• Local overrides — Git-ignored local configuration fragments (add .atmos.d/local/ to .gitignore)

tip

The .atmos.d/ directory is ideal for configuration that shouldn't be in the main atmos.yaml, such as local developer settings or dynamically generated configuration. For environment-specific configuration overrides, use Profiles instead.

Windows Path Handling

When configuring paths in atmos.yaml on Windows, there are important considerations for how YAML interprets backslashes:

Windows Path Escaping

Backslashes (\) are treated as escape characters only inside double-quoted YAML scalars. Single-quoted and plain scalars treat backslashes literally. Use single quotes or plain scalars for Windows paths, or double-escape backslashes in double quotes.

Forward Slashes (Recommended)

# Forward slashes work on all platforms including Windows
components:
  terraform:
    base_path: "C:/Users/username/projects/components/terraform"

Escaped Backslashes

# Double backslashes to escape them in YAML
components:
  terraform:
    base_path: "C:\\Users\\username\\projects\\components\\terraform"

Single Quotes (Backslashes Literal)

# Single quotes treat backslashes as literal characters
components:
  terraform:
    base_path: 'C:\Users\username\projects\components\terraform'

Unquoted Paths

# Unquoted paths with forward slashes also work
components:
  terraform:
    base_path: C:/Users/username/projects/components/terraform

Best Practice

Use forward slashes (/) for all paths in atmos.yaml. They work correctly on all operating systems including Windows, Linux, and macOS.

Default CLI Configuration

If atmos.yaml is not found in any of the searched locations, Atmos uses the following default configuration:

atmos.yaml

base_path: "."
vendor:
  base_path: "./vendor.yaml"
components:
  terraform:
    base_path: components/terraform
    apply_auto_approve: false
    deploy_run_init: true
    init_run_reconfigure: true
    auto_generate_backend_file: true
  helmfile:
    base_path: components/helmfile
    use_eks: true
    kubeconfig_path: /dev/shm
stacks:
  base_path: stacks
  included_paths:
    - "orgs/**/*"
  excluded_paths:
    - "**/_defaults.yaml"
  name_pattern: "{tenant}-{environment}-{stage}"
workflows:
  base_path: stacks/workflows
logs:
  file: "/dev/stderr"
  level: Info
schemas:
  jsonschema:
    base_path: stacks/schemas/jsonschema
  opa:
    base_path: stacks/schemas/opa
templates:
  settings:
    enabled: true
    sprig:
      enabled: true
    gomplate:
      enabled: true
settings:
  list_merge_strategy: replace
  terminal:
    color: true
    max_width: 120
    pager: false
version:
  check:
    enabled: true
    frequency: daily

If Atmos does not find an atmos.yaml file and the default CLI config is used, and if you set the ENV variable ATMOS_LOGS_LEVEL to Debug (e.g. export ATMOS_LOGS_LEVEL=Debug) before executing Atmos commands, you'll see a message indicating that the default configuration is being used.

Configuration Sections

The atmos.yaml file is organized into the following sections:

Component Configuration

Section	Description
Components	Component type configuration (Terraform, Helmfile, Packer)
Terraform	Terraform/OpenTofu component settings
Helmfile	Helmfile component settings
Packer	Packer component settings
Stacks	Stack discovery and naming patterns

Settings

Section	Description
Settings	Global settings including list merge strategies and token injection
Imports	Import and merge multiple configuration files
Environment Variables	All available environment variables

Output and Display

Section	Description
Terminal Settings	Terminal display, color, width, and pager
Markdown Styling	Customize markdown rendering
Secret Masking	Automatic secret detection and masking
Logs	Logging level and output destination

Advanced Configuration

Section	Description
Profiles	Named configuration overrides for different environments
Custom Commands	Define custom Atmos commands
Aliases	Create shortcut names for commands
Templates	Go templates, Sprig, and Gomplate configuration
Workflows	Workflow definition paths
Vendor	Vendoring configuration and manifest paths
Stores	External key-value store configuration
Docs	Documentation generation for READMEs and release notes
Version	Automatic version checking and update notifications

Validation and Integration

Section	Description
Schemas	JSON Schema and OPA policy paths
Error Handling	Error formatting and Sentry integration
Integrations	Atlantis, Spacelift, and other integrations
Profiler	Performance profiling configuration
Telemetry	Usage analytics and telemetry settings

Viewing Your Configuration

Use atmos describe config to view your fully-merged CLI configuration:

atmos describe config

atmos describe config

See atmos describe config for more details.

Related Commands

📄️ atmos describe config

Inspect your merged configuration

See Also

• Profiles — Environment-specific configuration overrides
• Global Flags — Command-line flags that affect configuration
• Version Constraints — Enforce Atmos version requirements