### Run rio-vt example programs Source: https://rioterm.com/docs/rio-vt Commands to run the crate's runnable examples covering common paths: quickstart, sixel, kitty_image, selection, and resize. ```text cargo run -p rio-vt --example quickstart cargo run -p rio-vt --example sixel cargo run -p rio-vt --example kitty_image cargo run -p rio-vt --example selection cargo run -p rio-vt --example resize ``` -------------------------------- ### Run Rio Source: https://rioterm.com/docs/install/using-cargo Starts the Rio terminal after installation. ```sh rio ``` -------------------------------- ### Install scdoc and build man pages Source: https://rioterm.com/docs/command-line-interface Installs scdoc on macOS or Ubuntu/Debian, then builds and installs Rio's manual pages from the extra/man directory. After installation, use 'man' to access offline documentation. ```sh # Install scdoc (macOS) brew install scdoc # Install scdoc (Ubuntu/Debian) sudo apt install scdoc # Build and install man pages cd extra/man make sudo make install ``` -------------------------------- ### Install manual pages for Rio on FreeBSD Source: https://rioterm.com/docs/install/freebsd Install scdoc, build and install man pages from source, then access documentation with man commands. Requires git and sudo. ```bash # Install scdoc (required to build man pages) pkg install scdoc # Build and install man pages from source git clone https://github.com/raphamorim/rio.git cd rio/extra/man make sudo make install # Access documentation man rio # Main Rio manual man 5 rio # Configuration file format man 5 rio-bindings # Key bindings reference ``` -------------------------------- ### Install scdoc and build man pages Source: https://rioterm.com/docs/install/linux Commands to install scdoc on various Linux distributions and then build and install Rio's manual pages from source. After installation, access documentation with 'man rio', 'man 5 rio', and 'man 5 rio-bindings'. ```bash # Install scdoc (required to build man pages) # Ubuntu/Debian: sudo apt install scdoc # Arch Linux: sudo pacman -S scdoc # Fedora: sudo dnf install scdoc # openSUSE: sudo zypper install scdoc # Build and install man pages from source git clone https://github.com/raphamorim/rio.git cd rio/extra/man make sudo make install # Access documentation man rio # Main Rio manual man 5 rio # Configuration file format man 5 rio-bindings # Key bindings reference ``` -------------------------------- ### Single user Nix profile install for Rio Source: https://rioterm.com/docs/install/linux Install Rio imperatively using nix profile install with the flake reference github:raphamimor/rio/main. ```bash nix profile install github:raphamimor/rio/main ``` -------------------------------- ### Install Rio via Scoop Source: https://rioterm.com/docs/install/windows Use the Scoop package manager to install Rio. First add the 'extras' bucket, then install the 'rio' package. ```sh scoop bucket add extras scoop install rio ``` -------------------------------- ### Install Rio on Linux via Flatpak Source: https://rioterm.com/ Installs Rio from Flathub using Flatpak. The command is `flatpak install flathub com.rioterm.Rio`. ```bash $ flatpak install flathub com.rioterm.Rio ``` -------------------------------- ### Complete Platform Configuration Example Source: https://rioterm.com/docs/config A comprehensive example combining all platform override features: theme, env-vars, window, shell, and renderer overrides for macOS, Linux, and Windows. Demonstrates field-level merging for window and renderer, and complete replacement for shell. ```toml # Global configuration theme = "default" env-vars = ["EDITOR=vim"] [window] width = 1024 height = 768 opacity = 0.9 [shell] program = "/bin/bash" args = ["--login"] [platform] # macOS: Override only specific fields macos.theme = "dracula" macos.env-vars = ["HOMEBREW_PREFIX=/opt/homebrew"] macos.window.opacity = 1.0 # Other window fields preserved macos.renderer.backend = "Metal" macos.shell = { program = "/bin/zsh", args = ["-l"] } # Linux: Different overrides linux.window.mode = "Maximized" linux.renderer.backend = "Vulkan" # Windows: Complete customization windows.theme = "nord" windows.env-vars = ["WINDOWS_VAR=value"] windows.shell = { program = "pwsh", args = ["-NoLogo"] } ``` -------------------------------- ### Install Rio via WinGet Source: https://rioterm.com/docs/install/windows Use the WinGet package manager to install Rio. The command installs the package with the ID 'raphamorim.rio'. ```sh winget install -e --id raphamorim.rio ``` -------------------------------- ### Install dependencies on Void Linux Source: https://rioterm.com/docs/install/build-from-source Installs required build libraries for Void Linux using xbps-install. ```sh xbps-install cmake freetype-devel expat-devel fontconfig-devel libxcb-devel pkg-config python3 ``` -------------------------------- ### Full panel configuration example Source: https://rioterm.com/docs/config Complete panel configuration combining padding, row-gap, column-gap, border-width, and border-radius. ```toml [panel] padding = [5] # Inner padding inside each panel row-gap = 10 # Vertical gap when split down column-gap = 15 # Horizontal gap when split right border-width = 2.0 # Border width around panels border-radius = 0.0 # Corner radius (0 = sharp) ``` -------------------------------- ### Install dependencies on FreeBSD Source: https://rioterm.com/docs/install/build-from-source Installs required build libraries for FreeBSD using pkg. ```sh pkg install cmake freetype2 fontconfig pkgconf python3 ``` -------------------------------- ### TOML key bindings configuration example Source: https://rioterm.com/docs/key-bindings Example configuration for the [bindings] section in Rio's config file. Shows how to bind keys with modifiers to actions, send escape sequences, remove existing bindings, and use panel resize actions. ```toml [bindings] keys = [ { key = "q", with = "super", action = "Quit" }, # Send escape sequence to clear screen and move cursor to home { key = "l", with = "control", esc = "\u001b[2J\u001b[H" }, # Remove existing keybind { key = "v", with = "control | shift", action = "none" }, # Panel resize actions (customize as needed) { key = "up", with = "control | super", action = "MoveDividerUp" }, { key = "down", with = "control | super", action = "MoveDividerDown" }, { key = "left", with = "control | super", action = "MoveDividerLeft" }, { key = "right", with = "control | super", action = "MoveDividerRight" }, ] ``` -------------------------------- ### Verify terminfo installation with infocmp Source: https://rioterm.com/docs/install/terminfo Checks that the rio terminfo entry is installed correctly. Run after installation to confirm everything works. ```sh # Check terminfo is installed infocmp rio ``` -------------------------------- ### Install terminfo from Rio repository Source: https://rioterm.com/docs/install/terminfo If you've cloned the Rio repository, use this command to install the terminfo from the misc directory. ```sh cd /path/to/rio sudo tic -xe xterm-rio,rio misc/rio.terminfo ``` -------------------------------- ### Build and install manual pages for Rio Source: https://rioterm.com/docs/install/macos Builds and installs Rio manual pages from source. Requires scdoc. Provides commands to access the main manual, configuration file format, and key bindings reference. ```bash # Install scdoc (required to build man pages) brew install scdoc # Build and install man pages from source git clone https://github.com/raphamorim/rio.git cd rio/extra/man make sudo make install # Access documentation man rio # Main Rio manual man 5 rio # Configuration file format man 5 rio-bindings # Key bindings reference ``` -------------------------------- ### Install dependencies on Fedora Source: https://rioterm.com/docs/install/build-from-source Installs required build libraries for Fedora using dnf. ```sh dnf install cmake freetype-devel fontconfig-devel libxcb-devel libxkbcommon-devel g++ ``` -------------------------------- ### External command action with arguments Source: https://rioterm.com/docs/config Shows how to configure an external command action, either as a simple command string or with arguments using a table. The example uses 'xdg-open' and 'code --goto'. ```toml [hints.rules.action] command = "xdg-open" # Simple command # Or with arguments: command = { program = "code", args = ["--goto"] } ``` -------------------------------- ### Install dependencies on Debian/Ubuntu Source: https://rioterm.com/docs/install/build-from-source Installs required build libraries for Debian/Ubuntu using apt. Tested on Debian Bookworm. ```sh apt install cmake pkg-config libfreetype6-dev libfontconfig1-dev libxcb-xfixes0-dev libxkbcommon-dev python3 ``` -------------------------------- ### Manual quick install of Rio terminfo Source: https://rioterm.com/docs/install/terminfo For distributions that don't include Rio's terminfo, download and install it manually using curl and tic. ```sh # Download and install terminfo curl -o rio.terminfo https://raw.githubusercontent.com/raphamorim/rio/main/misc/rio.terminfo sudo tic -xe xterm-rio,rio rio.terminfo rm rio.terminfo ``` -------------------------------- ### Install dependencies on Arch Linux Source: https://rioterm.com/docs/install/build-from-source Installs required build libraries for Arch Linux using pacman. ```sh pacman -S cmake freetype2 fontconfig pkg-config make libxcb libxkbcommon python ``` -------------------------------- ### Shell Configuration Complete Replacement Example Source: https://rioterm.com/docs/config Shows that platform-specific shell configuration uses complete replacement. You must provide the full shell configuration for each platform override, as shown for Windows and Linux. ```toml [shell] program = "/bin/fish" args = ["--login"] [platform] # Shell is completely replaced on Windows windows.shell = { program = "pwsh", args = ["-l"] } # Shell is completely replaced on Linux linux.shell = { program = "tmux", args = ["new-session", "-c", "/var/www"] } ``` -------------------------------- ### Install Rio on FreeBSD via pkg Source: https://rioterm.com/ Installs Rio from the FreeBSD Ports collection using the pkg package manager. The command is `pkg install rio-terminal`. ```bash $ pkg install rio-terminal ``` -------------------------------- ### Manually install terminfo on Ubuntu 22.04 and older Debian/Ubuntu Source: https://rioterm.com/docs/install/linux Checks if the 'rio' terminfo is already installed; if not, downloads it from the Rio repository and installs it using tic. This is required for older Debian/Ubuntu versions where the terminfo is not included in system packages. ```bash # Check if terminfo is already installed infocmp rio 2>/dev/null || { # If not found, install it manually curl -o rio.terminfo https://raw.githubusercontent.com/raphamorim/rio/main/misc/rio.terminfo sudo tic -xe xterm-rio,rio rio.terminfo rm rio.terminfo } ``` -------------------------------- ### Platform-Specific Environment Variables Example Source: https://rioterm.com/docs/config Shows how to define platform-specific environment variables that are appended to the global env-vars list. Each platform can have its own additional variables. ```toml env-vars = ["GLOBAL_VAR=value"] [platform] macos.env-vars = ["MACOS_SPECIFIC=yes"] linux.env-vars = ["LINUX_SPECIFIC=yes"] windows.env-vars = ["WINDOWS_SPECIFIC=yes"] ``` -------------------------------- ### Padding examples with CSS-like syntax Source: https://rioterm.com/docs/config Defines outer padding around the window/tab area. Default is [10]. Examples show 1, 2, and 4 value syntax. ```toml # Apply 10px to all sides padding = [10] # top and bottom: 10px, right and left: 5px padding = [10, 5] # top: 10px, right: 5px, bottom: 15px, left: 20px padding = [10, 5, 15, 20] ``` -------------------------------- ### Install rio-terminfo on Arch Linux Source: https://rioterm.com/docs/frequently-asked-questions Install the rio-terminfo package using pacman to provide the terminfo for Rio terminal. ```bash sudo pacman -S rio-terminfo ``` -------------------------------- ### Check if terminfo is installed with infocmp rio Source: https://rioterm.com/docs/install/terminfo Run this command to verify that the Rio terminfo is installed. If it returns without errors, the terminfo is installed and Rio will work correctly. ```sh infocmp rio ``` -------------------------------- ### Install Rio via Homebrew Source: https://rioterm.com/docs/install/macos Installs Rio terminal using Homebrew. If Homebrew cannot find the rio cask, run 'brew update' first. ```sh brew install --cask rio ``` -------------------------------- ### Install ncurses-term on Debian 13+ / Ubuntu 24.04+ Source: https://rioterm.com/docs/install/terminfo These distributions include Rio's terminfo in the ncurses-term package. Run these commands to ensure it is installed. ```sh # Ensure ncurses-term is installed sudo apt update sudo apt install ncurses-term ``` -------------------------------- ### Install Rio on Linux via pacman Source: https://rioterm.com/ Installs Rio using the Arch Linux package manager pacman. The command is `pacman -S rio`. ```bash $ pacman -S rio ``` -------------------------------- ### Set window background opacity Source: https://rioterm.com/docs/config Sets the window background opacity. Default is 1.0. The example sets opacity to 0.5. ```toml [window] opacity = 0.5 ``` -------------------------------- ### Install rio-vt with cargo add Source: https://rioterm.com/docs/rio-vt Adds the rio-vt crate as a dependency. By default, it pulls in no renderer, GPU, or font-shaping dependencies. ```text cargo add rio-vt ``` -------------------------------- ### OSC 8 typical usage Source: https://rioterm.com/docs/features/hyperlinks Example of OSC 8 usage: OSC 8 ; ; https://example.com/ ST Link to example website OSC 8 ; ; ST. This creates a hyperlink that works with the default Rio hyperlink activation (Command on macOS, Shift on other platforms). ```bash OSC 8 ; ; https://example.com/ ST Link to example website OSC 8 ; ; ST ``` -------------------------------- ### Platform-Specific Themes Example Source: https://rioterm.com/docs/config Shows how to override the theme on specific platforms. The global theme is set to 'lucario', and macOS and Linux have their own theme overrides. ```toml theme = "lucario" [platform] macos.theme = "dracula" linux.theme = "nord" ``` -------------------------------- ### Verify terminfo on Debian 13+ / Ubuntu 24.04+ Source: https://rioterm.com/docs/install/linux Run this command to verify that the 'rio' terminfo is installed. These distributions include it in the ncurses-term package (version 6.5+), so no additional steps are needed. ```bash # Verify terminfo is installed infocmp rio ``` -------------------------------- ### Install Rio with Cargo Source: https://rioterm.com/docs/install/using-cargo Installs the Rio terminal using Cargo. Requires Rust and Cargo to be installed. May need additional platform-specific packages; see the building from source guide. ```sh cargo install rioterm --locked ``` -------------------------------- ### OSC 8 example with printf Source: https://rioterm.com/docs/features/hyperlinks A concrete bash command using printf to emit an OSC 8 hyperlink to https://raphamorim.io/rio/ with the text 'This is a link'. The escape sequences are \e]8;;...\e\ for the start and \e]8;;\e\ to end the hyperlink. ```bash printf '\e]8;;https://raphamorim.io/rio/\e\\This is a link\e]8;;\e\\\n' ``` -------------------------------- ### Install Rio via Chocolatey Source: https://rioterm.com/docs/install/windows Use the Chocolatey package manager to install Rio. The command installs the 'rio-terminal' package. ```sh choco install rio-terminal ``` -------------------------------- ### Configure window.background-image with path and opacity Source: https://rioterm.com/docs/config Sets an image as the window background. The image is uploaded into a dedicated GPU texture and stretched to cover the window. The 'path' field is required and must be absolute; 'opacity' defaults to 1.0 and is multiplied into the image's alpha channel. ```toml [window.background-image] path = "/Users/hugoamor/Desktop/musashi.png" opacity = 0.5 ``` -------------------------------- ### Valid configuration: theme at beginning of file Source: https://rioterm.com/docs/config Shows the correct placement of the 'theme' parameter at the beginning of the file, before any headers, so it is applied. ```toml theme = "dracula" # will work [editor] program = "vi" args = [] ``` -------------------------------- ### Install Rio on Linux via cargo Source: https://rioterm.com/ Installs Rio from source using Cargo, the Rust package manager. The command is `cargo install rioterm --locked`. ```bash $ cargo install rioterm --locked ``` -------------------------------- ### Basic hints configuration with URL rule Source: https://rioterm.com/docs/config Configures the hints system with an alphabet for labels and a rule for URLs. The action uses 'xdg-open' for Linux/BSD, with commented alternatives for macOS and Windows. The binding uses Control+Shift+O. ```toml [hints] # Characters used for hint labels alphabet = "jfkdls;ahgurieowpq" # URL hint example [[hints.rules]] regex = "(https://|http://)[^\u{0000}-\u{001F}\u{007F}-\u{009F}< >\"\\s{-}\\^⟨⟩`\\\\]+" hyperlinks = true post-processing = true persist = false [hints.rules.action] command = "xdg-open" # Linux/BSD # command = "open" # macOS # command = "explorer" # Windows [hints.rules.binding] key = "O" mods = ["Control", "Shift"] ``` -------------------------------- ### Show key events with kitty +kitten show_key Source: https://rioterm.com/docs/features/kitty-keyboard-protocol Alternative command to run the Kitty keyboard protocol demonstration using the kitty executable. ```sh kitty +kitten show_key -m kitty ``` -------------------------------- ### Install Rio via MacPorts Source: https://rioterm.com/docs/install/macos Installs Rio terminal using MacPorts. Requires sudo privileges. ```sh sudo port install rio ``` -------------------------------- ### Show key events with kitten show_key Source: https://rioterm.com/docs/features/kitty-keyboard-protocol Command to run the Kitty keyboard protocol demonstration using the kitten show_key tool. ```sh kitten show_key -m kitty ``` -------------------------------- ### Configure macOS shell to use fish from bin path Source: https://rioterm.com/docs/config Sets the shell program to /bin/fish with the --login argument for macOS. ```toml [shell] program = "/bin/fish" args = ["--login"] ``` -------------------------------- ### Select Webgpu renderer backend in Rio config Source: https://rioterm.com/docs/features/retroarch-shaders Sets the `backend` to `Webgpu` in the `[renderer]` section, required to use the filter chain on macOS and Linux after building with the `wgpu` feature. ```toml [renderer] backend = "Webgpu" ``` -------------------------------- ### Basic URL hint configuration in rio.toml Source: https://rioterm.com/docs/features/hints Configures a URL hint rule with alphabet, regex, hyperlinks, post-processing, persist, action, mouse, and binding settings. The action uses xdg-open for Linux/BSD, with commented alternatives for macOS and Windows. ```toml [hints] # Characters used for hint labels (should be easy to type) alphabet = "jfkdls;ahgurieowpq" # URL hint example [[hints.rules]] regex = "(https://|http://|ftp://)[^\u{0000}-\u{001F}\u{007F}-\u{009F}< >\"\\s{-}\\^⟨⟩`\\\\]+" hyperlinks = true post-processing = true persist = false [hints.rules.action] command = "xdg-open" # Linux/BSD # command = "open" # macOS # command = "explorer" # Windows [hints.rules.mouse] enabled = true mods = [] [hints.rules.binding] key = "O" mods = ["Control", "Shift"] ``` -------------------------------- ### Show Rio CLI help with rio --help Source: https://rioterm.com/docs/command-line-interface Displays the full command-line usage and options for the Rio terminal. The output lists options such as -e/--command, -w/--working-dir, --write-config, --log-file, --title-placeholder, -h, and -V. ```sh $ rio --help A hardware-accelerated GPU terminal emulator powered by WebGPU, focusing to run in desktops and browsers Usage: rio [OPTIONS] Options: -e, --command ... Command and args to execute (must be last argument) -w, --working-dir Start the shell in the specified working directory --write-config [] Writes the config to a given path or the default location --log-file Writes the logs to a file inside the config directory --title-placeholder Start window with specified title -h, --help Print help -V, --version Print version ``` -------------------------------- ### Serialize terminal screen to text or ANSI Source: https://rioterm.com/docs/rio-vt Uses FormatOptions::plain() to get plain UTF-8 text and contents_formatted() to get bytes with escape sequences. Useful for reconnect snapshots, logs, or feeding terminal state to another process. ```rust use rio_vt::crosswords::formatter::FormatOptions; let plain = term.format(FormatOptions::plain()); // plain UTF-8 text let ansi = term.contents_formatted(); // bytes with escape sequences ``` -------------------------------- ### Home-Manager flake configuration for Rio Source: https://rioterm.com/docs/install/linux Add this Nix flake to your Home-Manager configuration to enable Rio via programs.rio.enable and set the package to rio.packages.${pkgs.system}.rio. ```nix { inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; rio.url = "github:raphamimor/rio/main"; }; outputs = { self, nixpkgs, rio }: { homeConfigurations.your-username = nixpkgs.lib.homeManagerConfiguration { pkgs = import nixpkgs; modules = [ ({ pkgs, ... }: { programs.rio.enable = true; package = rio.packages.${pkgs.system}.rio; }) ]; }; }; } ``` -------------------------------- ### Install rio terminfo manually on Ubuntu 22.04 and older Debian/Ubuntu Source: https://rioterm.com/docs/frequently-asked-questions Rio's .deb packages don't include terminfo, so install it manually using curl and tic. This resolves errors about unknown terminal type or non-working functional keys. ```bash curl -o rio.terminfo https://raw.githubusercontent.com/raphamorim/rio/main/misc/rio.terminfo sudo tic -xe xterm-rio,rio rio.terminfo rm rio.terminfo ``` -------------------------------- ### External command hint actions Source: https://rioterm.com/docs/features/hints Shows two ways to configure an external command action: a simple command string and a command with arguments using a table. ```toml [hints.rules.action] command = "xdg-open" # Simple command # Or with arguments command = { program = "code", args = ["--goto"] } ``` -------------------------------- ### Set window.windows-use-no-redirection-bitmap to false Source: https://rioterm.com/docs/config Windows-specific option that sets WS_EX_NOREDIRECTIONBITMAP. The example shows the default value false. ```toml [window] windows-use-no-redirection-bitmap = false ``` -------------------------------- ### Create custom theme foobar.toml Source: https://rioterm.com/docs/config Defines a custom theme file with color fields for background, foreground, selection, navigation, search, regular, dim, and light colors. Missing fields will use Rio's defaults. ```toml # ~/.config/rio/themes/foobar.toml [colors] background = "" foreground = "" # Selection selection-background = "" selection-foreground = "" # Navigation tabs = "" tabs-active = "" bar = "" split = "" cursor = "" vi-cursor = "" # Search search-match-background = "" search-match-foreground = "" search-focused-match-background = "" search-focused-match-foreground = "" # Regular colors black = "" blue = "" cyan = "" green = "" magenta = "" red = "" tabs = "" white = "" yellow = "" # Dim colors dim-black = "" dim-blue = "" dim-cyan = "" dim-foreground = "" dim-green = "" dim-magenta = "" dim-red = "" dim-white = "" dim-yellow = "" # Light colors light-black = "" light-blue = "" light-cyan = "" light-foreground = "" light-green = "" light-magenta = "" light-red = "" light-white = "" light-yellow = "" ``` -------------------------------- ### Display images with Kitty graphics protocol tools Source: https://rioterm.com/docs/features/kitty-graphics-protocol Use these commands to display images in Rio via the Kitty graphics protocol. The first uses kitty's built-in tool, while the others are compatible alternatives. ```bash # Using kitty's built-in tool kitty +kitten icat image.png # Using other compatible tools chafa --format=kitty image.png timg -p kitty image.png ``` -------------------------------- ### Configure Windows shell to use PowerShell (pwsh) Source: https://rioterm.com/docs/config Sets the shell program to pwsh with no arguments for Windows. ```toml [shell] program = "pwsh" args = [] ``` -------------------------------- ### Ignore binding completely with 'None' Source: https://rioterm.com/docs/key-bindings Use 'None' as a no-op to completely ignore/disable a binding. In this example, pressing 'n' with 'super' does nothing. ```toml [bindings] keys = [ { key = "n", with = "super", action = "None" } ] ``` -------------------------------- ### Configure macOS shell to use tmux installed by Homebrew Source: https://rioterm.com/docs/config Sets the shell program to /opt/homebrew/bin/tmux with arguments to create a new session in /var/www. ```toml [shell] program = "/opt/homebrew/bin/tmux" args = ["new-session", "-c", "/var/www"] ``` -------------------------------- ### URL Opener hint rule (TOML) Source: https://rioterm.com/docs/features/hints Configures a hint rule that matches URLs and opens them with xdg-open. Bound to Control+Shift+O. Requires post-processing and hyperlinks enabled. ```toml [[hints.rules]] regex = "(https://|http://)[^\u{0000}-\u{001F}\u{007F}-\u{009F}< >\"\\s{-}\\^⟨⟩`\\\\]+" hyperlinks = true post-processing = true [hints.rules.action] command = "xdg-open" [hints.rules.binding] key = "O" mods = ["Control", "Shift"] ``` -------------------------------- ### Set renderer.target-fps to 120 Source: https://rioterm.com/docs/config Limits the maximum frames per second Rio attempts to draw. Disabled by default. Example sets target-fps to 120. ```toml [renderer] target-fps = 120 ```