Configuration

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:

Local project: config.toml, config.yaml, or config.json in current directory
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

boolean

default:"true"

Allow local ./config.toml to override global ~/.dx/config.toml settings.

boolean

default:"true"

Enable global Markdown rendering. Can be toggled per-file with m key.

boolean

default:"true"

Dim baseline text in output view for better readability.

boolean

default:"true"

Display FPS counter in status bar for performance monitoring.

MOTD Settings

boolean

default:"true"

Enable soft-wrap for MOTD Markdown content.

string

Hex color for MOTD text. Examples: "#3B82F6", "#10B981"

Theme Settings

string

default:"dark"

Base color theme. Options: "dark" or "light"

string

Path to external YAML theme file (should end with .dx-theme)

object

Key-value pairs to override specific theme tokens

[theme_overrides]
primary = "#FF6B6B"
background = "#1A1A1A"

string

Directory containing *.dx-theme files for theme selection

Status Bar

object

Configuration for the bottom status bar

Show Status Options

string

Static text to display in status bar

string

Command to run for dynamic status updates (outputs one line)

Example:

[status]
text = "dx v2.0"
# or
command = "date '+%H:%M'"

Telemetry

object

Optional telemetry for failed command logs

Show Telemetry Options

boolean

default:"false"

Enable sending failed command logs to endpoint

string

HTTP endpoint for telemetry POST requests

Example:

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

Auto-Update

object

Automatic build and relaunch configuration

Show Update Options

boolean

default:"false"

Build and relaunch dx on startup

string

default:"cargo build --release"

Command used for building before relaunch

string

Path to executable for relaunch (defaults to target/release/dx)

boolean

default:"true"

Reuse current CLI arguments on relaunch

Example:

[update]
on_start = true
build_cmd = "cargo build --release"
relaunch_path = "target/release/dx"
preserve_args = true

Asciinema Integration

object

Recording and live streaming configuration

Show Asciinema Options

boolean

default:"false"

Master switch for asciinema integration

boolean

default:"false"

Wrap external (passthrough) commands with asciinema

boolean

default:"false"

Wrap update relaunch sessions with asciinema

string

Directory to save recordings (defaults to current directory)

string

default:"dx"

Filename prefix; final name becomes <prefix>-<unix_timestamp>.cast

string

Recording title shown by asciinema

boolean

default:"false"

Quiet mode (suppresses asciinema prompts)

boolean

default:"false"

Overwrite existing recording files

boolean

default:"false"

Use live streaming instead of recording

string

default:"remote"

Streaming mode: "remote" or "local"

string

For local mode: address like "127.0.0.1:9000"

string

For remote mode: STREAM-ID or WebSocket URL

Example:

[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

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

Getting started

Features

AI Native

Configuration

Configuration Files

Basic Settings

MOTD Settings

Theme Settings

Status Bar

Telemetry

Auto-Update

Asciinema Integration

Complete Example

​Configuration Files

​Basic Settings

​MOTD Settings

​Theme Settings

​Status Bar

​Telemetry

​Auto-Update

​Asciinema Integration

​Complete Example

Configuration Files

Basic Settings

MOTD Settings

Theme Settings

Status Bar

Telemetry

Auto-Update

Asciinema Integration

Complete Example