Skip to main content

Terminal Settings

Atmos provides configurable terminal settings that allow you to customize the output appearance, including syntax highlighting for YAML and JSON outputs. These settings can be configured in your atmos.yaml configuration file.

You will learn

  • Configure syntax highlighting for terminal output
  • Customize color schemes and formatting options
  • Control output pagination and line wrapping
  • Set display preferences for different output formats

General Terminal Settings​

Configure general terminal behavior. These are also the default settings if not specified in your atmos.yaml:

settings:
  terminal:
    max_width: 120        # Maximum width for terminal output
    pager: false          # Pager disabled by default (set to true, or pager name like 'less' to enable)
    color: true           # Enable colored output (default: true)
    unicode: true         # Use Unicode characters in output
    tab_width: 2          # Number of spaces for YAML indentation (default: 2)

Configuration Precedence​

Atmos follows a clear precedence order for terminal settings, with command-line flags having the highest priority:

Pager Configuration Precedence​

  1. CLI Flags (highest priority): --pager=false, --pager=less
  2. NO_PAGER Environment Variable: NO_PAGER=1 (standard CLI convention)
  3. ATMOS_PAGER Environment Variable: ATMOS_PAGER=less
  4. PAGER Environment Variable: PAGER=more (system default)
  5. Configuration File (lowest priority): settings.terminal.pager: true

Color Configuration Precedence​

  1. NO_COLOR Environment Variable (highest priority): NO_COLOR=1 (disables all color)
  2. CLICOLOR=0: CLICOLOR=0 (disables color unless forced)
  3. CLICOLOR_FORCE: CLICOLOR_FORCE=1 (forces color even for non-TTY)
  4. Force Flags: --force-color or ATMOS_FORCE_COLOR=true (forces TrueColor)
  5. Disable Flags: --no-color or ATMOS_NO_COLOR=true (disables color)
  6. Enable Flags: --color or ATMOS_COLOR=true (enables color only if TTY)
  7. Configuration File (lowest priority): settings.terminal.color: true (enables color only if TTY)
  8. Default: Automatically detects TTY and terminal capabilities

Force Flags for Screenshot Generation​

Atmos provides force flags to generate consistent terminal output regardless of the environment. These are particularly useful for screenshot generation, documentation, and testing.

--force-tty and ATMOS_FORCE_TTY​

Force TTY mode with sane defaults when terminal detection fails:

  • Forces IsTTY() to return true even when not connected to a terminal
  • Uses default dimensions: width=120, height=40
  • Enables all TTY-dependent features (colors, icons, formatting)

Use cases:

  • Screenshot generation for documentation
  • Recording terminal sessions with tools like vhs
  • CI/CD environments where TTY detection fails

Example:

# Generate screenshot with consistent output
atmos terraform plan --force-tty --force-color | screenshot.sh

# Using environment variables
ATMOS_FORCE_TTY=true ATMOS_FORCE_COLOR=true atmos describe stacks | vhs record.tape

--force-color, ATMOS_FORCE_COLOR, and CLICOLOR_FORCE​

Force TrueColor (24-bit) output even when not a TTY:

  • ATMOS_FORCE_COLOR and CLICOLOR_FORCE are equivalent and both fully supported
  • CLICOLOR_FORCE is a standard environment variable (CLI Colors)
  • Forces TrueColor profile regardless of terminal detection
  • Overrides automatic color degradation
  • Useful when piping to tools that preserve ANSI codes

Important distinction:

  • --color / ATMOS_COLOR - Enables color only if TTY (respects terminal capabilities)
  • --force-color / ATMOS_FORCE_COLOR / CLICOLOR_FORCE - Forces TrueColor even for non-TTY (for screenshots)

Example:

# Normal piped output - automatically disables color
atmos terraform output | jq .vpc_id

# Force color when piping to color-aware tool
atmos describe stacks --force-color | bat

# Screenshot generation
atmos describe config --force-tty --force-color > screenshot.ansi

Automatic Color Degradation​

Atmos automatically degrades color output based on terminal capabilities:

  1. TrueColor (24-bit, 16 million colors) - Modern terminals (iTerm2, Windows Terminal)
  2. 256 colors - Terminals with TERM=*-256color
  3. 16 colors (ANSI) - Basic terminals with TERM=xterm
  4. No color - Non-TTY, piped output, or when color is disabled

Automatic behavior:

  • When piping output: atmos describe stacks | grep vpc - color automatically disabled
  • When redirecting: atmos terraform output > file.txt - color automatically disabled
  • When using --force-color: Color preserved even when piping

Syntax Highlighting​

You can customize the syntax highlighting behavior for terminal output using the following settings:

settings:
  terminal:
    # Main terminal settings
    pager: true                     # Enable pager for all terminal output
    max_width: 120                  # Maximum width for terminal output
    color: true                     # Enable colored output

    # Syntax highlighting specific settings
    syntax_highlighting:
      enabled: true                 # Enable/disable syntax highlighting
      formatter: terminal           # Output formatter
      theme: dracula                # Color scheme to use
      line_numbers: false           # Show line numbers
      wrap: false                   # Wrap long lines

Terminal Configuration Options​

max_width
Maximum width for terminal output (default: 120)
pager

Configure pager behavior for output display.

  • false or empty: Pager disabled (default)
  • true or on: Enable pager with system default
  • Pager command (e.g., less, more): Use specific pager program
  • Environment variables: NO_PAGER (disable), ATMOS_PAGER, PAGER (system default)
  • CLI control: --pager global flag
color

Enable colored terminal output (default: true).

  • Environment variables: NO_COLOR (standard), ATMOS_NO_COLOR, ATMOS_COLOR, COLOR
  • CLI control: --no-color global flag
unicode
Use Unicode characters in output (default: true)
tab_width
Number of spaces for YAML indentation (default: 2)

Syntax Highlighting Configuration Options​

enabled
Enable or disable syntax highlighting (default: true)
formatter
Output formatter (default: terminal)
theme

Color scheme for syntax highlighting. Available options include:

  • vim
  • monokai
  • github
  • dracula
  • ...and many other standard themes

You can find the full list of supported themes here.

line_numbers
Show line numbers in output (default: false)
wrap
Wrap long lines (default: false)

Example Usage​

The syntax highlighting is automatically applied when using commands that output YAML or JSON, such as:

# Display config in YAML format with syntax highlighting
atmos describe config -f yaml
# Display config in JSON format with syntax highlighting
atmos describe config
NOTE:

When the output is piped to another command, syntax highlighting is automatically disabled to ensure compatibility:

# Syntax highlighting is disabled when piping
atmos describe config | grep base_path

Supported Themes​

Atmos supports a wide range of themes for syntax highlighting. You can find the full list of supported themes here.