> ## Documentation Index
> Fetch the complete documentation index at: https://usedx.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete guide to dx configuration options and settings

dx uses `config.toml` (or `config.yaml`/`config.json`) files to customize behavior. Configuration can be set globally (`~/.dx/config.toml`) or per-project (`./config.toml`).

## Configuration Files

dx looks for configuration in this order:

1. **Local project**: `config.toml`, `config.yaml`, or `config.json` in current directory
2. **Global**: `~/.dx/config.toml`, `~/.dx/config.yaml`, or `~/.dx/config.json`

Project configuration overrides global settings when `allow_project_override` is true (default).

## Basic Settings

<ResponseField name="allow_project_override" type="boolean" default="true">
  Allow local `./config.toml` to override global `~/.dx/config.toml` settings.
</ResponseField>

<ResponseField name="markdown_enabled" type="boolean" default="true">
  Enable global Markdown rendering. Can be toggled per-file with `m` key.
</ResponseField>

<ResponseField name="output_dim" type="boolean" default="true">
  Dim baseline text in output view for better readability.
</ResponseField>

<ResponseField name="show_fps" type="boolean" default="true">
  Display FPS counter in status bar for performance monitoring.
</ResponseField>

## MOTD Settings

<ResponseField name="motd_wrap" type="boolean" default="true">
  Enable soft-wrap for MOTD Markdown content.
</ResponseField>

<ResponseField name="motd_color" type="string">
  Hex color for MOTD text. Examples: `"#3B82F6"`, `"#10B981"`
</ResponseField>

## Theme Settings

<ResponseField name="theme" type="string" default="dark">
  Base color theme. Options: `"dark"` or `"light"`
</ResponseField>

<ResponseField name="theme_file" type="string">
  Path to external YAML theme file (should end with `.dx-theme`)
</ResponseField>

<ResponseField name="theme_overrides" type="object">
  Key-value pairs to override specific theme tokens

  ```toml theme={null}
  [theme_overrides]
  primary = "#FF6B6B"
  background = "#1A1A1A"
  ```
</ResponseField>

<ResponseField name="theme_dir" type="string">
  Directory containing `*.dx-theme` files for theme selection
</ResponseField>

## Status Bar

<ResponseField name="status" type="object">
  Configuration for the bottom status bar

  <Expandable title="Status Options">
    <ResponseField name="text" type="string">
      Static text to display in status bar
    </ResponseField>

    <ResponseField name="command" type="string">
      Command to run for dynamic status updates (outputs one line)
    </ResponseField>
  </Expandable>
</ResponseField>

Example:

```toml theme={null}
[status]
text = "dx v2.0"
# or
command = "date '+%H:%M'"
```

## Telemetry

<ResponseField name="telemetry" type="object">
  Optional telemetry for failed command logs

  <Expandable title="Telemetry Options">
    <ResponseField name="enabled" type="boolean" default="false">
      Enable sending failed command logs to endpoint
    </ResponseField>

    <ResponseField name="endpoint" type="string">
      HTTP endpoint for telemetry POST requests
    </ResponseField>
  </Expandable>
</ResponseField>

Example:

```toml theme={null}
[telemetry]
enabled = true
endpoint = "https://api.example.com/telemetry"
```

## Auto-Update

<ResponseField name="update" type="object">
  Automatic build and relaunch configuration

  <Expandable title="Update Options">
    <ResponseField name="on_start" type="boolean" default="false">
      Build and relaunch dx on startup
    </ResponseField>

    <ResponseField name="build_cmd" type="string" default="cargo build --release">
      Command used for building before relaunch
    </ResponseField>

    <ResponseField name="relaunch_path" type="string">
      Path to executable for relaunch (defaults to `target/release/dx`)
    </ResponseField>

    <ResponseField name="preserve_args" type="boolean" default="true">
      Reuse current CLI arguments on relaunch
    </ResponseField>
  </Expandable>
</ResponseField>

Example:

```toml theme={null}
[update]
on_start = true
build_cmd = "cargo build --release"
relaunch_path = "target/release/dx"
preserve_args = true
```

## Asciinema Integration

<ResponseField name="asciinema" type="object">
  Recording and live streaming configuration

  <Expandable title="Asciinema Options">
    <ResponseField name="enabled" type="boolean" default="false">
      Master switch for asciinema integration
    </ResponseField>

    <ResponseField name="external" type="boolean" default="false">
      Wrap external (passthrough) commands with asciinema
    </ResponseField>

    <ResponseField name="on_relaunch" type="boolean" default="false">
      Wrap update relaunch sessions with asciinema
    </ResponseField>

    <ResponseField name="dir" type="string">
      Directory to save recordings (defaults to current directory)
    </ResponseField>

    <ResponseField name="file_prefix" type="string" default="dx">
      Filename prefix; final name becomes `<prefix>-<unix_timestamp>.cast`
    </ResponseField>

    <ResponseField name="title" type="string">
      Recording title shown by asciinema
    </ResponseField>

    <ResponseField name="quiet" type="boolean" default="false">
      Quiet mode (suppresses asciinema prompts)
    </ResponseField>

    <ResponseField name="overwrite" type="boolean" default="false">
      Overwrite existing recording files
    </ResponseField>

    <ResponseField name="stream" type="boolean" default="false">
      Use live streaming instead of recording
    </ResponseField>

    <ResponseField name="stream_mode" type="string" default="remote">
      Streaming mode: `"remote"` or `"local"`
    </ResponseField>

    <ResponseField name="local_addr" type="string">
      For local mode: address like `"127.0.0.1:9000"`
    </ResponseField>

    <ResponseField name="remote" type="string">
      For remote mode: STREAM-ID or WebSocket URL
    </ResponseField>
  </Expandable>
</ResponseField>

Example:

```toml theme={null}
[asciinema]
enabled = true
external = true
dir = "./recordings"
file_prefix = "session"
title = "dx Session"
quiet = true
overwrite = true

# For live streaming
stream = true
stream_mode = "remote"
remote = "your-stream-id"
```

## Complete Example

```toml theme={null}
# ~/.dx/config.toml (global) or ./config.toml (project)

allow_project_override = true
markdown_enabled = true
output_dim = true
theme = "dark"
show_fps = true
motd_wrap = true
motd_color = "#3B82F6"

[status]
command = "git branch --show-current 2>/dev/null || echo 'not a git repo'"

[telemetry]
enabled = false
endpoint = "https://api.example.com/logs"

[update]
on_start = false
build_cmd = "cargo build --release"
preserve_args = true

[asciinema]
enabled = true
external = true
dir = "../recordings"
file_prefix = "dx"
quiet = true
overwrite = true
```