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

> **Key points**
>
> - 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`:

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

## 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`:

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

Or use an environment variable:

```bash
export ATMOS_THEME=dracula
atmos describe config
```

### Available Themes

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

```bash
# 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`](/cli/commands/theme/list) - List available themes
- [`atmos theme show`](/cli/commands/theme/show) - Preview a specific theme
- [`atmos list themes`](/cli/commands/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. **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:**

```bash
# 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](https://bixense.com/clicolors/))
- 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:**

```bash
# 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:

```yaml
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`
  )
- **`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`

### 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](https://xyproto.github.io/splash/docs/).
- **`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:

```bash
# 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:
>
> ```bash
> # 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](https://xyproto.github.io/splash/docs/).