---
name: "rio"
section: "5"
platform: "linux"
package: "rio"
version: "0.5.28-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/rio/5"
---

# rio(5)

TOML configuration file format.

## NAME

Rio - TOML configuration file format.

## SYNTAX

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

## LOCATION

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*

## GENERAL

**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"*\]

## WINDOW

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

## FONTS

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.

## COLORS

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\>"*

Inactive tab title color. Tab island backgrounds are derived from the window background color automatically.

**tabs-active** = *"\<string\>"*

Active tab title 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.

## CURSOR

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*

## SCROLL

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*

## NAVIGATION

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.

## SHELL

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.

## EDITOR

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.

## BINDINGS

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.

## RENDERER

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*

## DEVELOPER

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*

## SEE ALSO

[**rio**(1)](/rio/1.md)

## BUGS

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

## MAINTAINERS

- •

  Raphael Amorim \<rapha850@gmail.com\>