# Logs

Configure where Atmos writes logs and at what verbosity level. Proper log configuration is essential for debugging and for CI/CD pipelines where you need to separate log output from command results.

## Configuration

Logs are configured in the `logs` section:

**File:** `atmos.yaml`

```yaml
logs:
  # File or standard file descriptor to write logs to
  # Can also be set using 'ATMOS_LOGS_FILE' ENV var, or '--logs-file' command-line argument
  file: "/dev/stderr"
  # Supported log levels: Trace, Debug, Info, Warning, Off
  # Can also be set using 'ATMOS_LOGS_LEVEL' ENV var, or '--logs-level' command-line argument
  level: Warning
  # Enable log color when available (default: true)
  # Can also use ATMOS_LOGS_COLOR or --logs-color
  color: true
```

- **`logs.color`**

  Controls color in Atmos logs independently of UI output. `true` (default) uses
  color when available, preserving terminal and CI detection, including GitHub Actions.
  `false` removes ANSI escapes from logs. Use `--force-color` or `ATMOS_FORCE_COLOR=true`
  to force color when log color is enabled. Override this boolean with
  `ATMOS_LOGS_COLOR` or `--logs-color=false`, with CLI flags taking precedence over
  the environment and config. `--no-color` and nonempty `NO_COLOR` always disable
  color, including startup logs, even with `logs.color: true` or `--force-color`.
- **`logs.file`**

  The file to write Atmos logs to. Logs can be written to any file or any standard file descriptor, including `/dev/stdout`, `/dev/stderr` and `/dev/null`. If omitted, `/dev/stderr` will be used so logs never contaminate pipeable command output on stdout. Can also be set using `ATMOS_LOGS_FILE` environment variable.
- **`logs.level`**

  Log level. Supported log levels are `Trace`, `Debug`, `Info`, `Warning`, `Off`. If omitted, `Warning` will be used, so informational messages are hidden unless requested. The default changed from `Info` to `Warning` in the 2025-09 [edition](/cli/configuration/edition); to keep the old verbosity, set `logs.level: Info` explicitly or pin `edition: "2025-08"`. If the log level is set to `Off`, Atmos will not log any messages (note that this does not prevent other tools like Terraform from logging). Can also be set using `ATMOS_LOGS_LEVEL` environment variable.

## Disabling Logs

To prevent Atmos from logging any messages (except for the outputs of the executed commands), you can do one of the following:

- Set `logs.file` or the ENV variable `ATMOS_LOGS_FILE` to `/dev/null`
- Set `logs.level` or the ENV variable `ATMOS_LOGS_LEVEL` to `Off`

## Plain Log Files

To keep terminal UI colors while producing a plain log file:

```shell
atmos --logs-level=debug --logs-file=/tmp/atmos.log --logs-color=false version
```

To disable colors in both logs and UI output, use `--no-color` or set `NO_COLOR=1`.
`CLICOLOR=0` also disables automatic color, but can be overridden by forced color.
`CLICOLOR=1` permits automatic color without forcing it into pipes or files. If
`CLICOLOR=1` and nonempty `NO_COLOR` are both set, `NO_COLOR` wins and logs stay plain.
See [color precedence](/cli/configuration/settings/terminal#color-configuration-precedence).
Logging color controls apply to Atmos's own logs, not output from child processes.

## Logs in CI/CD Pipelines

When you set the log level to `Debug` or `Trace`, Atmos will log additional messages before printing the output of an executed command.

### Problem: Mixed Output

Consider the `atmos describe affected` command with verbose logging:

**File:** `atmos.yaml`

```yaml
logs:
  file: "/dev/stdout"
  level: Trace
```

```shell
Checking out Git ref 'refs/remotes/origin/HEAD' ...
Checked out Git ref 'refs/remotes/origin/HEAD'

Current HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
BASE: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD

Changed files:

examples/quick-start-advanced/Dockerfile
examples/quick-start-advanced/atmos.yaml

Affected components and stacks:

[
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-uw2-prod",
      "stack_slug": "plat-uw2-prod-vpc",
      "affected": "stack.vars"
   }
]
```

With `logs.level: Trace` and `logs.file: "/dev/stdout"`, all messages and JSON output go to the same stream. This breaks JSON parsing with tools like `jq`.

### Solution: Separate Streams

Set `logs.file` to `/dev/stderr` in `atmos.yaml`:

**File:** `atmos.yaml`

```yaml
logs:
  file: "/dev/stderr"
  level: Trace
```

Now log messages go to `/dev/stderr` while command output goes to `/dev/stdout`:

```shell
# NOTE: These messages are printed to /dev/stderr

Checking out Git ref 'refs/remotes/origin/HEAD' ...
Checked out Git ref 'refs/remotes/origin/HEAD'
Current HEAD: ffd2154e1daa32357b75460b9f45d268922b51e1 refs/heads/update-logs
BASE: f7aa382aa8b3d48be8f06cfdb27aad344b89aff4 HEAD


# NOTE: This JSON output is printed to /dev/stdout

[
   {
      "component": "vpc",
      "component_type": "terraform",
      "component_path": "examples/quick-start-advanced/components/terraform/vpc",
      "stack": "plat-uw2-prod",
      "stack_slug": "plat-uw2-prod-vpc",
      "affected": "stack.vars"
   }
]
```

This allows `jq` to parse the JSON output without errors while still logging debug information.

## Environment Variables

- **`ATMOS_LOGS_FILE`**
  File or standard file descriptor to write logs to.
- **`ATMOS_LOGS_LEVEL`**
  Log level: 
  `Trace`
  , 
  `Debug`
  , 
  `Info`
  , 
  `Warning`
  , 
  `Off`
  .

## See Also

- [CLI Configuration](/cli/configuration) — Overview of CLI configuration
- [Environment Variables](/cli/environment-variables) — All configuration environment variables