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
• Pace terminal output for demos and recordings
• 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)
    theme: atmos          # Terminal color theme (default: atmos)
    speed: 0              # Lines per second for paced output (0 = unlimited)
    links: auto           # How long URLs are delivered: auto, osc8, clipboard, or raw
    help:
      filter: true        # Bare --help shows a focused view; --help=all prints everything

Terminal Theme

Atmos supports customizable terminal themes that control the appearance of CLI output, including tables, markdown rendering, help text, and status messages. Themes provide consistent color schemes optimized for either dark or light terminal backgrounds.

Setting a Theme

Configure the theme in your atmos.yaml:

settings:
  terminal:
    theme: atmos  # Use the default Atmos theme

Or use an environment variable:

export ATMOS_THEME=dracula
atmos describe config

Available Themes

Atmos includes hundreds of pre-configured themes. To browse available themes:

# List all available themes
atmos theme list

# Show only recommended themes
atmos theme list --recommended

# Preview a specific theme
atmos theme show dracula

Popular themes include:

• atmos (default) - Cloud Posse's optimized theme for Atmos
• dracula - Dark theme with vibrant colors
• github - Light theme matching GitHub's style
• monokai - Dark theme popular in code editors
• solarized-dark / solarized-light - Precision colors designed for long-term use

For a complete list of themes and detailed previews, see:

• atmos theme list - List available themes
• atmos theme show - Preview a specific theme
• atmos list themes - Alternative list command

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. Disable Controls (highest priority): nonempty NO_COLOR, --no-color, or ATMOS_NO_COLOR=true disable all color, including forced color and logs. --no-color=false overrides ATMOS_NO_COLOR, but nonempty NO_COLOR always disables 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. Enable Flags: --color or ATMOS_COLOR=true (enables color only if TTY)
6. Configuration File (lowest priority): settings.terminal.color: true (enables color only if TTY)
7. Default: Automatically detects TTY and terminal capabilities

Log color has one more control, logs.color (--logs-color, ATMOS_LOGS_COLOR). Setting it to false keeps logs plain while terminal output stays colored. See Logs.

CLICOLOR remains supported independently of NO_COLOR. CLICOLOR=1 (or another nonzero value) permits automatic color on supported terminals and in color-capable CI environments such as GitHub Actions; it does not force color into pipes or files. CLICOLOR=0 disables automatic color, including the version logo, unless color is explicitly forced. An empty CLICOLOR leaves detection unchanged.

When the variables contradict each other, nonempty NO_COLOR wins:

CLICOLOR=1 NO_COLOR=1 atmos version                 # Plain output
CLICOLOR=1 NO_COLOR=0 atmos version                 # Also plain: NO_COLOR is nonempty
CLICOLOR=1 NO_COLOR= atmos version                  # Automatic terminal/CI detection
CLICOLOR=0 atmos version                           # Plain output
CLICOLOR=0 atmos --force-color version              # Forced color
CLICOLOR=0 NO_COLOR=1 atmos --force-color version   # Plain output: NO_COLOR wins

These rules apply to Atmos output; child processes may implement their own color conventions.

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

Terminals That Never Answer Queries

Terminal UI libraries (such as Bubble Tea and termenv, which Atmos and many other CLI tools use) ask the terminal for its foreground color, background color, and cursor position at startup, then wait for the reply. Atmos answers these queries itself for the pseudo-terminals it owns, such as recorded sessions and child commands that run without forwarded input.

Terminals and harnesses that never answer these queries (some CI runners, remote shells, and AI tool harnesses) can make startup wait about 5 seconds for each query. In those environments, set TERM=screen-256color (or tmux-256color) so the libraries skip the queries:

TERM=screen-256color atmos terraform plan vpc -s dev

Long URLs

Some commands hand you a URL to open by hand. atmos auth login, for example, shows the AWS sign-in URL in case the browser does not open. AWS IAM Identity Center now returns sign-in URLs of more than 500 characters. When AWS also provides a short verification address, where you enter the code from the prompt, Atmos shows that instead. A URL of up to 80 columns is shown inside the prompt's box. A longer one is never drawn inside the box, because the border would wrap into the URL and end up in the text you copy. It is delivered below the box instead, in the form settings.terminal.links selects. The same setting applies to the console sign-in URL that atmos auth console shows when it does not open a browser:

settings:
  terminal:
    links: auto   # auto (default), osc8, clipboard, or raw

auto

Show a short clickable link (an OSC 8 hyperlink) such as Open AWS sign-in when the terminal is known to support one, and print the full URL otherwise.

osc8

Always show the short clickable link. Use this when your terminal supports hyperlinks but Atmos cannot tell, which is common inside a container (such as Geodesic or a devcontainer) or over SSH.

clipboard

Copy the URL to the system clipboard, replacing its current contents, and confirm it with a Copied the URL to your clipboard message. If the operating system has no clipboard Atmos can reach, Atmos asks the terminal to copy the URL instead (an OSC 52 request), warns that the copy could not be confirmed, and also prints the full URL, because a terminal does not acknowledge that request.

raw

Always print the full URL as plain text. The terminal wraps it without inserting any characters, so it can be selected and copied intact.

Terminals offer no way to ask whether they support hyperlinks, so auto recognizes terminals by the environment variables they set:

• iTerm2 (3.1+) and VS Code (1.72+): TERM_PROGRAM (iTerm.app or vscode) with TERM_PROGRAM_VERSION
• WezTerm, Ghostty, and Orca: TERM_PROGRAM (WezTerm, ghostty, or Orca)
• Ghostty and kitty: TERM (xterm-ghostty or xterm-kitty)
• kitty: KITTY_WINDOW_ID
• Windows Terminal: WT_SESSION
• VTE-based terminals such as GNOME Terminal (0.50+): VTE_VERSION
• Konsole (20.12+): KONSOLE_VERSION
• Orca: ORCA_PANE_KEY

Anything else gets the full URL, including TERM=dumb, sessions inside tmux or screen (detected by TMUX and STY), and containers that do not pass those variables through. Set links: osc8 there if your terminal does support hyperlinks, or pass the variables into the container.

auto also honors the FORCE_HYPERLINK environment variable used by other command-line tools: FORCE_HYPERLINK=1 turns the clickable link on and FORCE_HYPERLINK=0 turns it off, whatever the terminal, including inside tmux. It applies only when the effective mode is auto: a mode other than auto set by --links, ATMOS_TERMINAL_LINKS, or settings.terminal.links takes precedence over it.

When output is not a terminal (piped, redirected, or in CI), Atmos always prints the full URL and never touches the clipboard, whatever this setting says.

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
    speed: 0                        # Lines per second for paced output (0 = unlimited)

    # 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)

theme

Terminal color theme for Atmos CLI output (default: atmos). Controls colors for tables, markdown, help text, and status messages.

• Environment variable: ATMOS_THEME
• List available themes: atmos theme list
• Preview themes: atmos theme show <theme-name>
• Popular options: atmos, dracula, github, monokai, solarized-dark, solarized-light

speed

Pace terminal output at the configured number of lines per second. Use this for demos, tutorials, and terminal recordings where instant output is hard to read. A value of 0 disables pacing and preserves the default unlimited output behavior.

• Environment variable: ATMOS_TERMINAL_SPEED

links

How a URL too long for a prompt's box is delivered: auto (default), osc8, clipboard, or raw. See Long URLs.

• Environment variable: ATMOS_TERMINAL_LINKS
• Command-line flag: --links

help.filter

Filter the bare --help output to a focused view that omits the GLOBAL FLAGS section (default: true). Use --help=all to print the full help output on demand. Set settings.terminal.help.filter: false (or ATMOS_HELP_FILTER=false) to always show the full output, including the GLOBAL FLAGS section.

• Environment variable: ATMOS_HELP_FILTER
• The default changed from false to true in the 2026-07 edition; a project pinned to an earlier edition keeps the unfiltered output.

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.