Skip to main content

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:

atmos.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; 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:

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

atmos.yaml
logs:
  file: "/dev/stdout"
  level: Trace
atmos describe affected
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:

atmos.yaml
logs:
  file: "/dev/stderr"
  level: Trace

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

atmos describe affected
# 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​