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:

--chdir / -C

Change the working directory before Atmos runs. Equivalent to running cd <directory> before executing atmos.

Use Cases:

  • Development workflow: Test local Atmos builds against different infrastructure repos
  • CI/CD: Run Atmos from a build directory while operating on infrastructure elsewhere
  • Multi-repo operations: Execute commands across multiple repos without changing your shell
  • Scripting: Simplify scripts that operate on different directories

Basic Usage:

# Run as if you did: cd /path/to/infra && atmos terraform plan
atmos -C /path/to/infra terraform plan vpc -s prod

# Use environment variable
ATMOS_CHDIR=/infrastructure atmos list components
How it differs from --base-path

--chdir: Changes the process working directory (calls os.Chdir())

  • Like running cd before atmos
  • ALL file operations use the new directory
  • Happens before any configuration loading

--base-path: Provides a path prefix for configuration (just a string)

  • Does not change the working directory
  • Used when joining paths: filepath.Join(basePath, componentPath)
  • Processed after --chdir

Examples showing the difference:

# Without any flags (current directory: /home/user)
atmos terraform plan
# Looks for atmos.yaml in: /home/user/atmos.yaml
# Resolves components from: /home/user/components/terraform/

# With --chdir (changes working directory)
atmos --chdir=/infra terraform plan
# Working directory changed to: /infra
# Looks for atmos.yaml in: /infra/atmos.yaml
# Resolves components from: /infra/components/terraform/

# With --base-path (working directory unchanged)
atmos --base-path=/infra terraform plan
# Working directory still: /home/user
# Base path prefix: /infra
# Looks for atmos.yaml using: /infra prefix
# Relative paths in config resolve from: /home/user

# With both flags
atmos --chdir=/home/user --base-path=/infra terraform plan
# First: changes working directory to /home/user
# Then: uses /infra as base path prefix
# Result: paths like /infra are resolved relative to /home/user
--base-path

Specify the Atmos project root directory. Use this when your atmos.yaml and components are in a non-standard location.

When to use it:

  • Your atmos.yaml and components are in a subdirectory
  • Using Atmos programmatically (like the Terraform provider)
  • Non-standard project layout where the Atmos root isn't the current directory

Basic Usage:

# Look for atmos.yaml and components using /custom/path as the base
atmos --base-path=/custom/path terraform plan vpc -s prod

# Combine with --chdir
atmos --chdir=/infra --base-path=./custom describe stacks
Technical details

What it does internally:

  • Sets atmosConfig.BasePath (a configuration value, not a directory change)
  • Used as a prefix when joining paths: filepath.Join(basePath, componentPath)
  • Constructs paths to: stacks, terraform components, helmfile components, packer components
  • Does not call os.Chdir() or change the working directory

Path resolution:

  • Supports both absolute and relative paths
  • Relative paths resolved using filepath.Abs() from current working directory
  • If --chdir was used, relative paths resolve from the NEW working directory
  • Can also use ATMOS_BASE_PATH environment variable

See --chdir section above for detailed comparison of how these flags interact.

--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/
  • Takes highest precedence: Overrides --force-color, --color, and all other color settings
--force-tty

Force TTY mode with sane defaults when terminal detection fails.

  • Useful for screenshot generation and documentation
  • Uses default terminal dimensions (width=120, height=40)
  • Forces IsTTY() to return true even when not a TTY
  • Can also use ATMOS_FORCE_TTY environment variable
  • Example: atmos terraform plan --force-tty --force-color | screenshot.sh
--force-color

Force TrueColor output even when not a TTY.

  • Useful for screenshot generation and documentation
  • Forces 24-bit TrueColor profile regardless of terminal detection
  • Overrides automatic color degradation
  • Can also use ATMOS_FORCE_COLOR environment variable
  • Note: The NO_COLOR environment variable or --no-color flag takes precedence and will disable color even when --force-color is set
  • Example: ATMOS_FORCE_COLOR=true atmos describe stacks | vhs record.tape
--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
--version

Print a minimal single-line Atmos CLI version and exit.

  • Outputs a simple atmos &lt;version&gt; format without styling or additional information
  • Does not perform update checks or support --check/--format flags
  • Available as a persistent flag on all commands
  • Always displays the Atmos version, not the version of underlying tools (Terraform, Helmfile, etc.)
  • For richer output and additional flags, use the atmos version command
  • Example: atmos --version

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

Profiling Flags​

--profiler-enabled

Enable the pprof HTTP profiling server.

  • Default: false
  • When enabled, starts an HTTP server for interactive profiling
  • Can also use ATMOS_PROFILER_ENABLED environment variable
--profiler-host

Host address for the profiling server.

  • Default: localhost
  • Use 0.0.0.0 to allow external connections (security consideration)
  • Can also use ATMOS_PROFILER_HOST environment variable
--profiler-port

Port for the profiling server.

  • Default: 6060
  • Can also use ATMOS_PROFILER_PORT environment variable
--profile-file

Write profiling data to the specified file (enables profiling automatically).

  • When specified, enables file-based profiling instead of server-based
  • File extension should match profile type (e.g., .prof for CPU, .out for trace)
  • Can also use ATMOS_PROFILE_FILE environment variable
--profile-type

Type of profile to collect when using --profile-file.

  • Options: cpu, heap, allocs, goroutine, block, mutex, threadcreate, trace
  • Default: cpu
  • Only used with --profile-file, ignored for server-based profiling
  • Can also use ATMOS_PROFILE_TYPE environment variable

Performance Heatmap Flags​

--heatmap

Display performance heatmap visualization after command execution.

  • Default: false
  • Shows function call counts, execution times, and performance metrics
  • Automatically tracks function execution with microsecond precision
  • Includes P95 latency calculations using High Dynamic Range histograms
  • Displays interactive TUI if terminal is available, otherwise static output
--heatmap-mode

Visualization mode for the performance heatmap.

  • Options: bar, ascii, sparkline, table
  • Default: bar
  • bar: Colored horizontal bar chart with function names and durations
  • ascii: Color-coded ASCII bars (Red >1ms, Orange >500µs, Yellow >100µs, Green <100µs)
  • sparkline: Compact sparklines showing relative performance
  • table: Interactive table with sortable columns
  • Only used with --heatmap flag

Environment Variables​

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

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

Core Environment Variables​

ATMOS_CHDIR

Change to the specified directory before executing any command.

  • Equivalent to the --chdir / -C flag
  • CLI flag takes precedence over this environment variable
  • Useful for CI/CD pipelines and scripting
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
  • Highest precedence: Takes precedence over ATMOS_FORCE_COLOR, CLICOLOR_FORCE, ATMOS_COLOR, and COLOR settings
  • Overrides --force-color flag
  • Both ATMOS_NO_COLOR and NO_COLOR are fully supported
ATMOS_FORCE_TTY

Force TTY mode with sane defaults when terminal detection fails.

  • Useful for screenshot generation and documentation
  • Uses default terminal dimensions (width=120, height=40)
  • Example: ATMOS_FORCE_TTY=true atmos describe stacks
ATMOS_FORCE_COLOR / CLICOLOR_FORCE

Force TrueColor output even when not a TTY.

  • Both ATMOS_FORCE_COLOR and CLICOLOR_FORCE are equivalent and fully supported
  • CLICOLOR_FORCE is a standard environment variable (https://bixense.com/clicolors/)
  • Useful for screenshot generation and piping to color-aware tools
  • Forces 24-bit TrueColor profile regardless of terminal detection
  • Note: NO_COLOR environment variable takes precedence and will disable color even when this is set
  • Example: ATMOS_FORCE_COLOR=true atmos describe config | bat
  • Example: CLICOLOR_FORCE=1 atmos terraform plan
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
ATMOS_PROFILER_ENABLED
Enable the pprof HTTP profiling server
ATMOS_PROFILER_HOST
Set the host address for the profiling server
ATMOS_PROFILER_PORT
Set the port for the profiling server
ATMOS_PROFILE_FILE
Set the file path for file-based profiling
ATMOS_PROFILE_TYPE
Set the profile type for file-based profiling (cpu, heap, allocs, goroutine, block, mutex, threadcreate, trace)

XDG Base Directory Environment Variables​

ATMOS_XDG_CACHE_HOME / XDG_CACHE_HOME

Override the default XDG cache directory for Atmos.

  • Default: ~/.cache on Linux/Unix, ~/Library/Caches on macOS, %LOCALAPPDATA% on Windows
  • Used for: Cache files (cache.yaml)
  • Example: ATMOS_XDG_CACHE_HOME=/custom/cache atmos describe stacks
ATMOS_XDG_DATA_HOME / XDG_DATA_HOME

Override the default XDG data directory for Atmos.

  • Default: ~/.local/share on Linux/Unix, ~/Library/Application Support on macOS, %LOCALAPPDATA% on Windows
  • Used for: File-based keyring storage
  • Example: ATMOS_XDG_DATA_HOME=/custom/data atmos auth login
ATMOS_XDG_CONFIG_HOME / XDG_CONFIG_HOME

Override the default XDG config directory for Atmos.

  • Default: ~/.config on Linux/Unix, ~/Library/Application Support on macOS, %APPDATA% on Windows
  • Reserved for future use
  • Example: ATMOS_XDG_CONFIG_HOME=/custom/config

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

Directory Change Examples​

# Change to infrastructure directory before running command
atmos --chdir=/path/to/infrastructure describe stacks

# Use short form (-C) for brevity
atmos -C /infra terraform plan vpc -s prod

# Relative path from current directory
atmos --chdir=../other-repo list components

# Use with other flags - chdir processes first
atmos -C /infra --base-path=./config describe component vpc -s dev

# Environment variable for scripting
export ATMOS_CHDIR=/infrastructure
atmos terraform apply vpc -s prod

# Development workflow - point dev binary at different repo
./build/atmos -C ~/projects/my-infrastructure describe stacks

# CI/CD pipeline example
cd /build
atmos --chdir=/infrastructure 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

Profiling Examples​

# File-based CPU profiling (default profile type)
atmos terraform plan vpc -s prod --profile-file=cpu.prof

# File-based memory heap profiling
atmos terraform plan vpc -s prod --profile-file=heap.prof --profile-type=heap

# File-based execution trace profiling
atmos terraform plan vpc -s prod --profile-file=trace.out --profile-type=trace

# Server-based profiling for interactive analysis
atmos terraform apply vpc -s prod --profiler-enabled --profiler-port=8080

# Environment variable configuration
export ATMOS_PROFILE_FILE=debug.prof
export ATMOS_PROFILE_TYPE=goroutine
atmos describe stacks

# Multiple profile types for comprehensive analysis
atmos terraform plan vpc -s prod --profile-file=cpu.prof --profile-type=cpu
atmos terraform plan vpc -s prod --profile-file=heap.prof --profile-type=heap
atmos terraform plan vpc -s prod --profile-file=trace.out --profile-type=trace

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​