Configuration reference#

Automexia can start without a configuration file. This reference describes the config.toml model, including settings beyond the current Linux Alpha. Use the first-session guide for release-tested examples. Windows and macOS sections describe planned support, not public packages or future source access.

File location and precedence#

Automexia uses one writable product root:

The root contains config.toml, themes/, extensions/, and logs/. AUTOMEXIA_CONFIG_HOME replaces the complete root. AUTOMEXIA_LOG_LEVEL overrides the configured log level. RIO_CONFIG_HOME is a read-only migration source and RIO_LOG_LEVEL is a deprecated value fallback; both warn once per start and should not be used for a new setup.

Create a starter file containing the canonical reference pointer without overwriting an existing file:

automexia --write-config
automexia --write-config ./automexia.toml

The main file must be a regular UTF-8 file no larger than 4 MiB. Each theme must be a regular UTF-8 file no larger than 1 MiB. Parse/read/theme failure is reported and runtime reload keeps the last known-good configuration.

Minimal example#

line-height = 1.22
confirm-before-quit = true
copy-on-select = false
scrollback-history-limit = 10000

[shell]
program = "bash"
args = []

[window]
width = 1280
height = 760
mode = "Windowed"
opacity = 1.0

[navigation]
mode = "Tab"
hide-if-single = false
max-tab-width = 200

[fonts]
size = 18.0
family = "Cascadia Code"

[cursor]
shape = "Block"
blinking = false

Top-level settings#

Shell and editor#

[shell]
program = "pwsh"
args = ["-NoLogo"]

[editor]
program = "code"
args = ["--wait"]

shell.program unset/empty selects the user's default shell (PowerShell on Windows; login shell on Unix). shell.args is an exact argument vector—no shell-string parsing. The editor defaults to Notepad on Windows and vi on Unix and is used by the open-config action.

Cursor, scroll, bell, and effects#

Window#

[window]
width = 1280
height = 760
columns = 120
rows = 30
mode = "Windowed"
opacity = 1.0
opacity-cells = false
blur = false
decorations = "Disabled"
colorspace = "Srgb"
quake-width-percentage = 1.0
quake-height-percentage = 0.4
background-image = { path = "D:/wallpaper.png", opacity = 0.25 }

Navigation and panes#

[navigation]
mode = "Tab"
current-working-directory = true
use-terminal-title = false
hide-if-single = false
use-split = true
open-config-with-split = true
unfocused-split-opacity = 0.7
unfocused-split-fill = "#00111f"
max-tab-width = 200

[panel]
margin = [2]
padding = [5]
row-gap = 0
column-gap = 0
border-width = 2
border-radius = 0

Pane-local tab rails and footers use responsive product invariants and have no v0.4 user setting. See Liquid Hacker UX.

Fonts#

[fonts]
size = 18.0
hinting = true
family = "Cascadia Code"
features = ["calt=1", "liga=1"]
use-drawable-chars = true
disable-warnings-not-found = false
additional-dirs = ["D:/fonts"]

[fonts.regular]
family = "Cascadia Code"
style = "default"
weight = 400

regular, bold, italic, and bold-italic each accept family, style, and optional CSS-style weight (100…900). style is "default", false to reuse regular, or a named face style. symbol-map entries use start, end, and font-family Unicode ranges. The default family is Cascadia Code and the default size is 18 pt. Runtime Ctrl/Cmd zoom is pane-local; reset returns to this configured size.

Renderer and keyboard#

Titles and developer logging#

Themes and colors#

A named theme lives at themes/<name>.toml:

[colors]
background = "#00111f"
foreground = "#d9e7f2"
cursor = "#2df0a0"
selection-background = "#164b70"
selection-foreground = "#ffffff"

Supported [colors] keys are:

background, foreground, black, red, green, yellow, blue, magenta, cyan, white,
light-black, light-red, light-green, light-yellow, light-blue, light-magenta,
light-cyan, light-white, dim-black, dim-red, dim-green, dim-yellow, dim-blue,
dim-magenta, dim-cyan, dim-white, dim-foreground, light-foreground, cursor,
vi-cursor, tabs, tabs-active, selection-background, selection-foreground,
split, split-active, search-match-background, search-match-foreground,
search-focused-match-background, search-focused-match-foreground,
hint-foreground, hint-background

Colors use #RRGGBB. Semantic DevOps identities retain their distinct anchor hues and apply contrast correction against the context background; user theme colors still own terminal ANSI output, search, and selection precedence.

Hints#

Hints discover URLs/paths without executing terminal text as a shell command. The default rule recognizes hyperlinks and local-looking paths and opens them through a platform handler with Ctrl+Alt+O.

[hints]
alphabet = "jfkdls;ahgurieowpq"

[[hints.rules]]
regex = "https://[^ ]+"
hyperlinks = true
post-processing = true
persist = false
action = "Copy"
mouse = { enabled = true, mods = ["Alt"] }
binding = { key = "O", mods = ["Control", "Alt"], mode = [] }

Built-in actions are Open, Copy, Paste, Select, and MoveViModeCursor. A command can be a string or { program, args }, but matched terminal content is hostile input: prefer Open, which uses exact platform handler arguments without shell interpretation.

Custom bindings#

The classic [bindings].keys table remains supported. Typed compatibility configuration selects a profile independently and layers exact entries after it:

[keyboard]
binding-profile = "ghostty-1.3"
binding-strict = true

[bindings]
keybinds = [
  "ctrl+shift+t=new_tab:inherit",
  "ctrl+x>ctrl+s=write_screen_file:copy,plain",
  "ctrl+u=unbind",
]

Profiles are automexia (the implicit default), ghostty-1.3 (pinned), and ghostty (a visible moving alias). Typed lines support logical, physical, and named keys; sequences; tables; chains; scopes; performability; consumption; and explicit unbinds. Compilation is bounded and atomic. Strict errors reject the candidate registry, so reload keeps the complete last-known-good profile, shortcuts, palette hints, and OS global hotkeys.

Legacy [bindings].keys entries still accept key, with, action, esc, and mode. A valid legacy user entry replaces its exact classic trigger; invalid or unknown actions are reported and do not erase a default. See Keyboard and input reference for public binding syntax and compatibility-profile limitations.

Platform-specific overrides#

Base settings load first; the active platform table selectively overrides shell, theme, supported window, navigation, and renderer fields and appends env-vars:

[platform.windows.shell]
program = "pwsh"
args = ["-NoLogo"]

[platform.linux.window]
decorations = "Enabled"

[platform.macos.renderer]
backend = "Metal"

Only fields represented by the platform override schema are accepted there. Top-level cursor, fonts, bindings, hints, panel, and developer settings remain shared. Navigation safety clamps run after the platform merge.

Runtime reload#

Bind the stable ReloadConfig action if you want an explicit reload shortcut:

[bindings]
keys = [
  { key = "F5", with = "control | shift", action = "ReloadConfig" },
]

Reload parses and prepares a complete replacement before swapping it into the application. A malformed, unreadable, oversized, or invalid-theme candidate is reported while every window keeps the last known-good configuration. Some launch-only settings affect newly created sessions/windows rather than a live PTY.

Migration and coexistence#

If no Automexia config exists on v0.4 startup, bounded migration can import Rio's config.toml, custom themes, and known extension activation markers. Automexia never modifies Rio data, copies logs/caches/executable content, or installs a rio alias. Existing Automexia files win. See Rio configuration migration.

Related references#

• Keyboard and input
• Shell integration
• Liquid Hacker UX