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. Current directory (./atmos.yaml)
4. Home directory (~/.atmos/atmos.yaml)
5. 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.

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.

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.

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

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)

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. Processing occurs after main config merges but before explicit import: entries

Example structure:

project/
├── atmos.yaml           # Main configuration
└── .atmos.d/
    ├── commands/
    │   └── custom.yaml  # Custom commands
    ├── profiles/
    │   └── ci.yaml      # CI profile
    └── settings/
        └── team.yaml    # Team-specific settings

Use cases:

• Custom commands — Drop in command definitions without modifying atmos.yaml
• Profiles — Add environment-specific profiles for CI/CD
• Team settings — Share team-specific defaults across projects
• Local overrides — Git-ignored local configuration fragments

tip

The .atmos.d/ directory is ideal for configuration that shouldn't be in the main atmos.yaml, such as local developer settings (add .atmos.d/local/ to .gitignore) or dynamically generated configuration.

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