RIO(5)

✨ NAME ✨

okay so RIO(5) is the manual page for Rio — literally the TOML configuration file format, bestie. If you're here, you're about to make Rio look and behave exactly how you want, and I'm obsessed. 🫶

🌈 SYNTAX 🌈

Rio's config file uses the TOML format. The format's spec lives at https://toml.io/en/v1.0.0 — that's the whole syntax vibe. ✨

🎀 LOCATION 🎀

heads up bestie: Rio doesn't create the config file for you. It just goes looking for one.

On UNIX systems, it checks these spots:

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

On Windows, it looks here:

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

No cap, that's the search order. 🦋

💖 GENERAL 💖

These are the general settings, bestie.

• 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. Window size, startup mode, decorations — the whole main-character window energy. 👑

• 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. Default: "Enabled".
  • Enabled — Normal window decorations.
  • Disabled — No window decorations.
  • Transparent (macOS only) — Transparent title bar.
  • Buttonless (macOS only) — Title bar without buttons.
• 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. Fonts are highkey the whole vibe, so yeah.

• 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. Slay.

• 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. Cursor vibes, but make it cute.

• 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. Scroll speed tuning, no cap.

• 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. Tabs and navigation display vibes.

• 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. What shell Rio runs, bestie.

• 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. The editor Rio opens config files with, periodt.

• 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. Keybinds, the moment, fr fr.

• 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. Graphics and performance settings, it's giving very technical. ✨

• 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. Debugging stuff, iykyk.

• 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) — go look at that one too, bestie.

🐛 BUGS 🐛

Found a bug? Please report it at https://github.com/raphamorim/rio/issues. Do it, the maintainers will love you for it. 🫶

👑 MAINTAINERS 👑

• Raphael Amorim <rapha850@gmail.com>

---

🎀 and that's the page, bestie! Source/version: File Formats Manual / RIO(5). Date: 2026-11-01. mwah 💋