Runa Configuration Guide

runa is configured via a TOML file. By default, it looks for your config in the following order:

Environment Variable: RUNA_CONFIG - If set, runa uses this path as the config file
```
export RUNA_CONFIG=/path/to/runa.toml
```
XDG Config Directory (Linux, macOS, and supported environments):
```
$XDG_CONFIG_HOME/runa/runa.toml
```
Default Path:
- ~/.config/runa/runa.toml (Linux/macOS)
- C:\Users\<UserName>\.config\runa\runa.toml (Windows)

runa is under active development and configuration options may change over time.

Installation

Cargo

You can install runa from crates.io

cargo install runa-tui

Arch Linux (AUR)

You can install runa from the AUR using an AUR helper like paru or yay:

yay -S runa

# or for binaries through the AUR
yay -S runa-bin

Homebrew

You can install runa via homebrew.

brew tap alexm-dev/tap
brew install runa

Scoop (Windows)

You can install runa via scoop.

scoop add bucket https://github.com/alexm-dev/scoop-bucket
scoop install runa

Pre-compiled Binaries

If you’d like to download Pre-compiled binaries instead of installing runa as a crate in cargo or via the AUR, you can grab the latest binaries for Linux, Windows and macOS from the Release page.

After downloading, add the rn (Linux/macOS) or rn.exe (Windows) binary to your system PATH to use runa from your terminal.

Build from source

Clone the repo and build with Cargo:

git clone https://github.com/alexm-dev/runa.git
cd runa
cargo build --release
cargo install --path .

Quick Start

If you don’t have a config file yet, generate one:

rn --init - Generates a minimal configuration
rn --init-full - Generates a full configuration with all options and inline documentation

Other useful commands:

rn --help - Shows the CLI help menu
rn --version - Displays the current installed version
rn --config-help - Displays documentation for configuration sections (e.g., rn --config-help general)

Optional Tool Integration

Some features require external tools to be installed:

bat - Fast, syntax-highlighted file previews (optional, highly recommended)
fd - Blazing fast recursive file/folder search (optional, highly recommended)

Both tools are completely optional. runa falls back to built-in methods if they’re not installed.

Install with your package manager:

sudo pacman -S bat fd           # Arch
sudo apt install bat fd-find    # Debian/Ubuntu
sudo dnf install bat fd-find    # Fedora/RHEL
brew install bat fd             # macOS

Configuration Sections

Each section below links to detailed documentation for all available options:

General Settings

File visibility, sorting, search behavior, and startup tabs.

Options: dirs_first, show_hidden, show_symlink, show_system, case_insensitive, always_show, max_find_results, move_to_trash, [general.startup]

Display Settings

Pane layout, borders, previews, file information, and UI styling.

Sections: [display], [display.layout], [display.preview_options], [display.info], [display.status]

Theme Configuration

Colors, icon coloring, styling, and widget customization.

Sections: [theme], color overrides for all UI elements, [theme.widget], [theme.status_line], [theme.info]

Editor Configuration

Editor program selection and per-extension/per-filename overrides.

Section: [editor]

Key Bindings

Keyboard shortcuts for all actions and navigation.

Section: [keys]

Complete Reference

For the complete list of all options with defaults and inline documentation, see:

runa_full.toml in assets/config
Run rn --init-full to generate a full config file with all options

Examples

Minimal Configuration

[general]
dirs_first = true
show_hidden = true

[display]
borders = "unified"

[editor]
default = "nvim"

Custom Theme with Layout

[display]
borders = "split"

[display.layout]
main = 40

[theme]
name = "gruvbox-dark"
selection.fg = "#EBA"
entry.fg = "#333333"
directory.fg = "magenta"

[theme.accent]
fg = "#00ff00"

[theme.widget]
position = [25, 60]
size = { w = 36, h = 20 }

Full Custom Setup

[general]
dirs_first = true
show_hidden = true
startup.tabs = ["cwd", "~/Downloads"]

[display]
borders = "unified"
titles = true
icons = true
preview_underline = false

[display.layout]
preview = 70

[display.preview_options]
method = "bat"
style = "numbers"

[display.info]
format = "{perms} | {size} | {mtime}"
date_format = "%d %b %y %H:%M"

[theme]
accent = "#8ac"
path.bg = "#333333"
status_line.bg = "#333333"
status_line.fg = "#8ac"

[editor]
default = "nvim"

[keys]
scroll_up = ["pgup"]
scroll_down = ["pgdn"]