# Configure Atmos CLI

The `atmos.yaml` configuration file controls the behavior of the `atmos` CLI and how Atmos will work with your project.

Therefore, this file should exist in the project repository alongside your Terraform components and Atmos stacks. It's also where you can [configure integrations](/cli/configuration/integrations), like with [native CI for GitHub Actions](/ci).

> **Key points**
>
> - How install `atmos` and make sure you're on a current version
> - How to configure `atmos.yaml` for your project's filesystem layout
> - How Atmos identifies stack configurations using context variables and naming patterns

- ## - Install Atmos
  Let's ensure you've [properly installed Atmos](/install) by running the following command.
  ```bash
  atmos version
  ```
  You should see something like this...

  > **Note**
  >
  > the current release of Atmos is 
  >
  > **_(see latest release)_**

- ## - Configure `atmos.yaml` for your project
  To configure Atmos to work with your project, we'll create a file called `atmos.yaml` to tell Atmos where to find the
  Terraform components and Atmos stacks. Almost everything in Atmos is configurable via this file.

  Below is the minimum recommended configuration for Atmos to work with Terraform and to configure [Atmos components](/components)
  and [Atmos stacks](/learn/stacks). Copy this YAML config below into your `atmos.yaml` file.

  > **Note**
  >
  > For the description of all the sections, refer to 
  >
  > [CLI Configuration](/cli/configuration)
  >
  > .

- ## - Understand what it's doing
  And here's what all that means...
  ### Basic Settings
  - **`stacks.name_pattern`**

    Atmos uses “slugs” to refer to stacks, which are defined by the `name_pattern` setting.
    Instead of relying on file names and locations, which can change, Atmos uses context variables (`namespace`, `tenant`, `environment`, `stage`)
    to identify the stack. For example, with the command `atmos terraform apply myapp -s dev`,
    Atmos interprets the slug `dev` using the pattern `{stage}` to locate the correct stack configuration
    in the stacks directory.
  - **`logs.level`**

    Set to `Info` to see the most helpful logs. You can also set it to `Trace` to see all the logs, which is helpful for debugging.
  - **`logs.file`**

    Set to `/dev/stderr` to send all of Atmos output to the standard error stream. This is useful when running Atmos in a CI/CD pipeline.
  ### Path Configuration
  Well-known paths are how Atmos finds all your stack configurations, components, and workflows. Here are the essential paths that you need to configure:
  - **`base_path`**
    The base path for components, stacks, and workflow configurations. We set it to 
    `./`
     so it will use the current working directory. Alternatively, we can override this behavior by setting the ENV var 
    `ATMOS_BASE_PATH`
     to point to another directory location.
  - **`components.terraform.base_path`**
    The base path to the Terraform components (Terraform root modules). As described in 
    [Configure Repository](/quick-start/advanced/configure-repository)
    , we've decided to put the Terraform components into the 
    `components/terraform`
     directory, and this setting tells Atmos where to find them. Atmos will join the base path (set in the 
    `ATMOS_BASE_PATH`
     ENV var) with 
    `components.terraform.base_path`
     to calculate the final path to the Terraform components
  - **`stacks.base_path`**
    The base path to the Atmos stacks. As described in 
    [Configure Repository](/quick-start/advanced/configure-repository)
    , we've decided to put the stack configurations into the 
    `stacks`
     directory, and this setting tells Atmos where to find them. Atmos will join the base path (set in the 
    `ATMOS_BASE_PATH`
     ENV var) with 
    `stacks.base_path`
     to calculate the final path to the stacks
  - **`stacks.included_paths`**
    List of file paths to the top-level stacks in the 
    `stacks`
     directory to include in search when Atmos searches for the stack where the component is defined when executing 
    `atmos`
     commands
  - **`stacks.excluded_paths`**
    List of file paths to the top-level stacks in the 
    `stacks`
     directory to exclude from search when Atmos searches for the stack where the component is defined when executing 
    `atmos`
     commands
  - **`workflows.base_path`**
    The base path to Atmos 
    [Workflows](/workflows)
     files
  Advanced Options
  - **`components.terraform.apply_auto_approve`**
    if set to 
    `true`
    , Atmos automatically adds the 
    `-auto-approve`
     option to instruct Terraform to apply the plan without
    asking for confirmation when executing 
    `terraform apply`
     command
  - **`components.terraform.deploy_run_init`**
    if set to 
    `true`
    , Atmos runs 
    `terraform init`
     before executing 
    [`atmos terraform deploy`](/cli/commands/terraform/deploy)
     command
  - **`components.terraform.init_run_reconfigure`**
    if set to 
    `true`
    , Atmos automatically adds the 
    `-reconfigure`
     option to update the backend configuration when executing 
    `terraform init`
     command
  - **`components.terraform.auto_generate_backend_file`**
    if set to 
    `true`
    , Atmos automatically generates the Terraform backend file from the component configuration when executing 
    `terraform plan`
     and 
    `terraform apply`
     commands
  - **`commands`**
    configuration for 
    [Atmos Custom Commands](/cli/configuration/commands)
  - **`schemas`**

    [JSON Schema](https://json-schema.org/) and [OPA Policy](https://www.openpolicyagent.org/) configurations for:
    - [Atmos Manifests Validation](/cli/configuration/schemas)
    - [Atmos Stack Validation](/validation/validating)
  ### Config File Location
  While placing `atmos.yaml` at the root of the repository will work for the `atmos` CLI, it will not work
  for [Component Remote State](/stacks/remote-state) because it uses
  the [terraform-provider-utils](https://github.com/cloudposse/terraform-provider-utils) Terraform provider. Terraform executes the provider from the
  component's folder (e.g. `components/terraform/vpc`), and we don't want to replicate `atmos.yaml` into every component's folder.

  Both the `atmos` CLI and [terraform-provider-utils](https://github.com/cloudposse/terraform-provider-utils) Terraform provider use the same `Go` code,
  which try to locate the [CLI config](/cli/configuration) `atmos.yaml` file before parsing and processing [Atmos stacks](/learn/stacks).

  This means that `atmos.yaml` file must be at a location in the file system where all processes can find it.

  How is the `atmos.yaml` file located?

  `atmos.yaml` is loaded from the following locations (from lowest to highest priority):
  - System dir (`/usr/local/etc/atmos/atmos.yaml` on Linux, `%LOCALAPPDATA%/atmos/atmos.yaml` on Windows)
  - Home dir (`~/.atmos/atmos.yaml`)
  - Current directory
  - ENV var `ATMOS_CLI_CONFIG_PATH`
  :::note

  Initial Atmos configuration can be controlled by these ENV vars:
  - **`ATMOS_CLI_CONFIG_PATH`**
    Directory that contains the 
    `atmos.yaml`
     (just the folder without the file name). It's not possible to change the filename at this time.
  - **`ATMOS_BASE_PATH`**
    Base path to the 
    `components/`
     and 
    `stacks/`
     folders.
  :::

**Ready to take the next step?**

Now you're ready to learn how to write your first Atmos component using Terraform.

Next Step[Read more](/quick-start/simple/write-components)
Deep Dive