# CLI Configuration

# CLI Configuration

Use the `atmos.yaml` configuration file to control the behavior of the [Atmos CLI](/cli)

Everything in the [Atmos CLI](/cli) is configurable. The defaults are established in the `atmos.yaml` configuration file. The CLI configuration should not be confused with [Stack configurations](/stacks), which have a different schema.

Think of this file as where you bootstrap the settings of your project. If you'll be using [Terraform](/components/terraform), then this is where you'd specify the command to run (e.g. [`opentofu`](/cli/configuration/components/terraform#using-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](/cli/configuration/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`.

```bash
# 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:

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

```bash
# 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](/cli/configuration/profiles).

### Glob Patterns

Atmos supports [POSIX-style Glob patterns](https://en.wikipedia.org/wiki/Glob_\(programming\)) 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.
  ```yaml
  base_path: !env ATMOS_BASE_PATH
  logs:
    level: !env ATMOS_LOG_LEVEL
  ```
  See the [`!env` documentation](/functions/yaml/env) for more details.
- **`!exec`**

  Execute shell scripts and use their output in configuration.
  ```yaml
  settings:
    account_id: !exec "aws sts get-caller-identity --query Account --output text"
  ```
  See the [`!exec` documentation](/functions/yaml/exec) for more details.
- **`!include`**

  Include other YAML files into the current configuration. Useful for sharing common settings across multiple configurations.
  ```yaml
  settings: !include "./common-settings.yaml"
  ```
  See the [`!include` documentation](/functions/yaml/include) 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.
  ```yaml
  base_path: !repo-root
  ```
  See the [`!repo-root` documentation](/functions/yaml/repo-root) 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.
  ```yaml
  base_path: !cwd
  # or with a relative path
  base_path: !cwd ./relative/path
  ```
  See the [`!cwd` documentation](/functions/yaml/cwd) 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.

```yaml
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:

```yaml
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:

```yaml
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:**

```bash
# 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:**

```bash
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](/cli/configuration/profiles) instead.
:::

### Windows Path Handling

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

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

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

### Escaped Backslashes

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

### Single Quotes (Backslashes Literal)

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

### Unquoted Paths

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

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

**File:** `atmos.yaml`

```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](/cli/configuration/components) | Component type configuration (Terraform, Helmfile, Packer) |
| [Terraform](/cli/configuration/components/terraform) | Terraform/OpenTofu component settings |
| [Helmfile](/cli/configuration/components/helmfile) | Helmfile component settings |
| [Packer](/cli/configuration/components/packer) | Packer component settings |
| [Stacks](/cli/configuration/stacks) | Stack discovery and naming patterns |

### Settings

| Section | Description |
|---------|-------------|
| [Settings](/cli/configuration/settings) | Global settings including list merge strategies and token injection |
| [Imports](/cli/configuration/imports) | Import and merge multiple configuration files |
| [Environment Variables](/cli/environment-variables) | All available environment variables |

### Output and Display

| Section | Description |
|---------|-------------|
| [Terminal Settings](/cli/configuration/settings/terminal) | Terminal display, color, width, and pager |
| [Markdown Styling](/cli/configuration/settings/markdown-styling) | Customize markdown rendering |
| [Secret Masking](/cli/configuration/settings/mask) | Automatic secret detection and masking |
| [Logs](/cli/configuration/logs) | Logging level and output destination |

### Advanced Configuration

| Section | Description |
|---------|-------------|
| [Toolchain](/cli/commands/toolchain/usage) | Tool version management and registry configuration |
| [Profiles](/cli/configuration/profiles) | Named configuration overrides for different environments |
| [Custom Commands](/cli/configuration/commands) | Define custom Atmos commands |
| [Aliases](/cli/configuration/aliases) | Create shortcut names for commands |
| [Templates](/cli/configuration/templates) | Go templates, Sprig, and Gomplate configuration |
| [Workflows](/cli/configuration/workflows) | Workflow definition paths |
| [Vendor](/cli/configuration/vendor) | Vendoring configuration and manifest paths |
| [Stores](/cli/configuration/stores) | External key-value store configuration |
| [Docs](/cli/configuration/docs) | Documentation generation for READMEs and release notes |
| [Version](/cli/configuration/version) | Version pinning, automatic checking, and constraint enforcement |

### Validation and Integration

| Section | Description |
|---------|-------------|
| [Schemas](/cli/configuration/schemas) | JSON Schema and OPA policy paths |
| [Error Handling](/cli/configuration/errors) | Error formatting and Sentry integration |
| [Integrations](/cli/configuration/integrations) | Atlantis, Spacelift, and other integrations |
| [Profiler](/cli/configuration/profiler) | Performance profiling configuration |
| [Telemetry](/cli/telemetry) | Usage analytics and telemetry settings |

## Viewing Your Configuration

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

```bash
atmos describe config
```

See [`atmos describe config`](/cli/commands/describe/config) for more details.

## Related Commands

## See Also

- [Profiles](/cli/configuration/profiles) — Environment-specific configuration overrides
- [Global Flags](/cli/global-flags) — Command-line flags that affect configuration
- [Version Constraints](/cli/configuration/version/constraint) — Enforce Atmos version requirements