Skip to main content

Global Flags

Global flags are available for all Atmos commands and control the overall behavior of the CLI. These flags take precedence over environment variables and configuration files.

Core Global Flags​

These flags are available for every Atmos command:

--base-path

Base path for the Atmos project. This is the root directory where Atmos will look for configuration files, stacks, and components.

  • Can also use ATMOS_BASE_PATH environment variable
  • Supports both absolute and relative paths
--config

Path to a specific Atmos configuration file.

  • Can be used multiple times for deep merging (later files override earlier ones)
  • Example: --config=base.yaml --config=override.yaml
--config-path

Path to a directory containing Atmos configuration files.

  • Can be used multiple times
  • Atmos looks for atmos.yaml, .atmos.yaml, atmos.yml, or .atmos.yml in these directories
--logs-level

Set the logging level for Atmos operations.

  • Options: Trace, Debug, Info, Warning, Off
  • Default: Warning
  • Can also use ATMOS_LOGS_LEVEL environment variable
--logs-file

File to write Atmos logs to.

  • Default: /dev/stderr
  • Can be any file path or standard file descriptor (/dev/stdout, /dev/stderr, /dev/null)
  • Can also use ATMOS_LOGS_FILE environment variable
--no-color

Disable colored terminal output.

  • Useful for CI/CD environments or when piping output
  • Can also use ATMOS_NO_COLOR or NO_COLOR environment variables
  • The NO_COLOR env var follows the standard from https://no-color.org/
--pager

Configure pager behavior for command output.

  • --pager (no value): Enable pager with default settings
  • --pager=true or --pager=on: Explicitly enable pager
  • --pager=false or --pager=off: Explicitly disable pager
  • Any non-boolean value is treated as a pager command (first token) with following tokens as arguments

Examples:

  • --pager='less -R': Use less with raw control chars
  • --pager="less --RAW-CONTROL-CHARS": Alternative syntax for less with options
  • export ATMOS_PAGER='less -R +Gg' or export PAGER='less -R': Set via environment variables

Environment Variables:

  • NO_PAGER: Standard CLI convention to disable pager (e.g., NO_PAGER=1)
  • ATMOS_PAGER: Atmos-specific pager configuration
  • PAGER: System default pager (fallback)

Precedence: --pager flag > NO_PAGER > ATMOS_PAGER > PAGER > config file

Default: Pager is disabled unless explicitly enabled

Note: Use quotes around the value to preserve spaces and prevent shell splitting when passing pager arguments. The NO_PAGER environment variable follows the standard CLI convention for disabling pagers.

--redirect-stderr

Redirect stderr to a file or file descriptor.

  • Can redirect to any file path or standard file descriptor
  • Example: --redirect-stderr=/dev/null to suppress error output

Command-Specific Flags​

These flags are available across multiple commands but not universally:

Processing Flags​

--process-templates

Enable or disable Go template processing in Atmos manifests.

  • Default: true
  • Available in: describe stacks, list, validate commands
--process-functions

Enable or disable YAML function processing in Atmos manifests.

  • Default: true
  • Available in: describe stacks, list, validate commands
--skip

Skip processing specific Atmos functions in manifests.

  • Can be used multiple times
  • Example: --skip=terraform.output --skip=include
  • Available in: describe commands

Output Flags​

--format / -f

Specify the output format.

  • Common values: yaml, json, table, csv
  • Available in: describe, list, validate commands
--file

Write output to a file instead of stdout.

  • Available in: describe, generate commands
--query / -q

Query output using JSONPath or yq expressions.

  • Example: --query='.components.vpc.vars'
  • Available in: describe commands

Environment Variables​

All global flags can be set using environment variables. The precedence order is:

  1. Command-line flags (highest priority)
  2. Environment variables
  3. Configuration file (atmos.yaml)
  4. Default values (lowest priority)

Core Environment Variables​

ATMOS_BASE_PATH
Sets the base path for the Atmos project
ATMOS_LOGS_LEVEL
Sets the logging level
ATMOS_LOGS_FILE
Sets the log file location
ATMOS_COLOR / COLOR

Enable or disable colored output.

  • Set to true to enable color (default)
  • Set to false to disable color
  • Both ATMOS_COLOR and COLOR are supported for maximum portability
ATMOS_NO_COLOR / NO_COLOR

Disable colored output (any non-empty value disables color).

  • NO_COLOR is a standard environment variable supported by many CLI tools (https://no-color.org/)
  • Maintained for portability across different systems and CI/CD environments
  • Takes precedence over ATMOS_COLOR/COLOR settings
  • Both ATMOS_NO_COLOR and NO_COLOR are fully supported
ATMOS_PAGER / PAGER

Configure pager settings.

  • PAGER is a standard Unix environment variable maintained for portability
  • Both ATMOS_PAGER and PAGER are supported to ensure compatibility across different systems

Portability Notes​

Atmos supports both standard and Atmos-prefixed environment variables to ensure maximum portability:

  • Standard Variables (NO_COLOR, COLOR, PAGER): Work across many CLI tools and Unix systems
  • Atmos Variables (ATMOS_NO_COLOR, ATMOS_COLOR, ATMOS_PAGER): Provide namespace isolation when needed

This dual support ensures your scripts and CI/CD pipelines work consistently across different environments without modification.

Examples​

Basic Usage​

# Disable color and pager for CI environment
atmos describe config --no-color --pager=off

# Use specific pager with custom log level
atmos describe stacks --pager=less --logs-level=Debug

# Multiple config files with base path
atmos --base-path=/infrastructure \
      --config=base.yaml \
      --config=override.yaml \
      terraform plan vpc -s prod

Pager Control Examples​

# Enable pager (multiple ways)
atmos describe config --pager                # Enable with default pager
atmos describe config --pager=true           # Explicitly enable
atmos describe config --pager=less           # Use specific pager
ATMOS_PAGER=true atmos describe config      # Via environment variable

# Disable pager (explicit)
atmos describe config --pager=false          # Explicitly disable
atmos describe config --pager=off            # Alternative syntax
ATMOS_PAGER=false atmos describe config     # Via environment variable

# Disable pager using NO_PAGER (standard CLI convention)
NO_PAGER=1 atmos describe config            # Standard way to disable pager
export NO_PAGER=1; atmos describe config    # Set for entire session

# Default behavior (no flag = pager disabled)
atmos describe config                        # Pager is OFF by default

Color Control Examples​

# Multiple ways to disable color
atmos describe config --no-color           # Using flag
NO_COLOR=1 atmos describe config          # Using NO_COLOR standard
ATMOS_NO_COLOR=1 atmos describe config    # Using ATMOS_NO_COLOR
ATMOS_COLOR=false atmos describe config   # Using ATMOS_COLOR
COLOR=false atmos describe config         # Using COLOR

# Explicitly enable color (overrides config file setting)
ATMOS_COLOR=true atmos describe config

Environment Variable Usage​

# Set environment variables
export ATMOS_PAGER=off
export ATMOS_COLOR=false
export ATMOS_LOGS_LEVEL=Debug

# Commands will use these settings
atmos describe config

CI/CD Configuration​

# Typical CI/CD settings
export ATMOS_NO_COLOR=true
export ATMOS_PAGER=off
export ATMOS_LOGS_LEVEL=Warning
export ATMOS_LOGS_FILE=/var/log/atmos.log

# Run commands without interactive features
atmos terraform apply --auto-approve

CI/CD Portability Example​

# These environment variables work across many tools, not just Atmos
export NO_COLOR=1        # Disables color in Atmos and other NO_COLOR-compliant tools
export ATMOS_PAGER=off  # Properly disables paging in Atmos

# Run various CLI tools - all respect the same env vars
atmos describe config
terraform plan
kubectl get pods
NOTE:

When output is piped to another command, Atmos automatically disables color output and pager to ensure compatibility:

# Color and pager automatically disabled
atmos describe stacks | grep production

See Also​