RIO(5) File Formats Manual RIO(5)

Rio - TOML configuration file format.

Rio's configuration file uses the TOML format. The format's specification can be found at https://toml.io/en/v1.0.0.

Rio doesn't create the config file for you, but it looks for one in the following locations on UNIX systems:

1.
$RIO_CONFIG_HOME/config.toml
2.
$XDG_CONFIG_HOME/rio/config.toml
3.
$HOME/.config/rio/config.toml

On Windows, the config file will be looked for in:

1.
%USERPROFILE%\AppData\Local\rio\config.toml

theme = "<string>"

Theme name to use. When set, colors defined in the configuration file will be ignored.

Default: None

confirm-before-quit = true | false

Require confirmation before quitting.

Default: true

draw-bold-text-with-light-colors = true | false

When true, bold text is drawn using the bright color variants.

Default: false

env-vars = ["<string>",]

Environment variables to set for spawned processes.

Example:

env-vars = ["TERM=xterm-256color", "COLORTERM=truecolor"]

This section documents the [window] table of the configuration file.

width = <integer>

Window width in pixels.

Default: 600

height = <integer>

Window height in pixels.

Default: 400

mode = "Windowed" | "Maximized" | "Fullscreen"

Window startup mode.

Default: "Windowed"

opacity = <float>

Background opacity as a floating point number from 0.0 to 1.0.

Default: 1.0

blur = true | false

Request compositor to blur content behind transparent windows.

Default: false

decorations = "Enabled" | "Disabled" | "Transparent" | "Buttonless"

Window decorations.

Enabled

Normal window decorations.
Disabled
No window decorations.
Transparent (macOS only)
Transparent title bar.
Buttonless (macOS only)
Title bar without buttons.

Default: "Enabled"

background-image = { path = "<string>", opacity = <float> }

Window background image. The image is uploaded once into a dedicated GPU texture and stretched to cover the full window.

path

Path to the background image file.
opacity
Image opacity from 0.0 to 1.0. Default 1.0.

This section documents the [fonts] table of the configuration file.

size = <float>

Font size in points.

Default: 18.0

family = "<string>"

Font family name. When set, overrides all font variant families.

Default: "cascadiacode"

features = ["<string>",]

OpenType font features to enable.

Example:

features = ["ss02", "ss03", "liga"]

use-drawable-chars = true | false

Use built-in drawable characters for box drawing.

Default: true

disable-warnings-not-found = true | false

Disable warnings when fonts are not found.

Default: false

additional-dirs = ["<string>",]

Additional directories to search for fonts.

regular = { family = "<string>", style = "<string>", width = "<string>", weight = <integer> }

Regular font configuration.

Default: { family = "cascadiacode", style = "Normal", width = "Normal", weight = 400 }

bold = { family = "<string>", style = "<string>", width = "<string>", weight = <integer> }

Bold font configuration.

Default: { family = "cascadiacode", style = "Normal", width = "Normal", weight = 800 }

italic = { family = "<string>", style = "<string>", width = "<string>", weight = <integer> }

Italic font configuration.

Default: { family = "cascadiacode", style = "Italic", width = "Normal", weight = 400 }

bold-italic = { family = "<string>", style = "<string>", width = "<string>", weight = <integer> }

Bold italic font configuration.

Default: { family = "cascadiacode", style = "Italic", width = "Normal", weight = 800 }

extras = [{ family = "<string>" },]

Additional fonts to load.

emoji = { family = "<string>" }

Emoji font configuration.

Default: Built-in Twemoji font

hinting = true | false

Enable font hinting.

Default: true

symbol-map = [{ chars = "<string>", family = "<string>" },]

Map specific character ranges to fonts.

This section documents the [colors] table of the configuration file.

Colors are specified using their hexadecimal values with a # prefix: #RRGGBB or #RRGGBBAA.

background = "<string>"

Default background color.

foreground = "<string>"

Default foreground color.

cursor = "<string>"

Cursor color.

vi-cursor = "<string>"

Vi mode cursor color.

black, red, green, yellow, blue, magenta, cyan, white = "<string>"

Standard ANSI colors.

light-black, light-red, light-green, light-yellow, light-blue, light-magenta, light-cyan, light-white = "<string>"

Bright ANSI colors.

dim-black, dim-red, dim-green, dim-yellow, dim-blue, dim-magenta, dim-cyan, dim-white = "<string>"

Dim ANSI colors.

tabs = "<string>"

Tab bar background color.

tabs-foreground = "<string>"

Tab bar text color.

tabs-active = "<string>"

Active tab background color.

tabs-active-foreground = "<string>"

Active tab text color.

tabs-active-highlight = "<string>"

Active tab highlight color.

bar = "<string>"

Navigation bar background color.

split = "<string>"

Split separator color.

search-match-background = "<string>"

Search match background color.

search-match-foreground = "<string>"

Search match text color.

search-focused-match-background = "<string>"

Focused search match background color.

search-focused-match-foreground = "<string>"

Focused search match text color.

selection-background = "<string>"

Selection background color.

selection-foreground = "<string>"

Selection text color.

This section documents the [cursor] table of the configuration file.

shape = "block" | "underline" | "beam"

Cursor shape.

Default: "block"

blinking = true | false

Enable cursor blinking.

Default: false

blinking-interval = <integer>

Cursor blinking interval in milliseconds. Range: 350-1200.

Default: 800

This section documents the [scroll] table of the configuration file.

multiplier = <float>

Scroll speed multiplier.

Default: 3.0

divider = <float>

Scroll divider for fine-tuning.

Default: 1.0

This section documents the [navigation] table of the configuration file.

mode = "NativeTab" | "Tab" | "Plain"

Navigation display mode.

Default: "Tab"

clickable = true | false

Enable clickable navigation elements.

Default: false

use-current-path = true | false

Show current working directory in navigation.

Default: false

color-automation = [{ program = "<string>", path = "<string>", color = "<string>" },]

Automatic color assignment based on program or path.

This section documents the [shell] table of the configuration file.

program = "<string>"

Shell program to execute.

Default: System default shell

args = ["<string>",]

Arguments to pass to the shell.

This section documents the [editor] table of the configuration file.

program = "<string>"

Editor program for opening configuration files.

Default: "vi"

args = ["<string>",]

Arguments to pass to the editor.

This section documents the [bindings] table of the configuration file.

keys = [{ key = "<string>", with = "<string>", action = "<string>" },]

Key bindings configuration.

key

Key name (e.g., "q", "Enter", "F1").

with

Modifier keys: "super", "alt", "ctrl", "shift". Multiple modifiers can be combined with |.

action

Action to perform. Available actions include: "Quit", "CreateWindow", "CloseWindow", "Copy", "Paste", "ScrollUp", "ScrollDown", "ToggleViMode", "OpenConfigEditor", and many others.

This section documents the [renderer] table of the configuration file.

performance = "High" | "Low"

Rendering performance mode.

Default: "High"

backend = "Automatic" | "GL" | "Vulkan" | "DX12" | "Metal"

Graphics backend to use.

Default: "Automatic"

disable-renderer-when-unfocused = true | false

Disable rendering when window is unfocused to save power.

Default: false

level = <integer>

Rendering level (0-3).

Default: 3

This section documents the [developer] table of the configuration file.

log-level = "OFF" | "ERROR" | "WARN" | "INFO" | "DEBUG" | "TRACE"

Log level for debugging.

Default: "OFF"

enable-log-file = true | false

Write logs to file.

Default: false

enable-fps-counter = true | false

Display FPS counter.

Default: false

rio(1)

Found a bug? Please report it at https://github.com/raphamorim/rio/issues.

•
Raphael Amorim <rapha850@gmail.com>
2026-05-13