runa-tui 0.10.0

A fast, keyboard-focused terminal file manager (TUI). Highly configurable and lightweight.
runa-tui-0.10.0 is not a library.
Visit the last successful build: runa-tui-0.5.3

runa - rn

Build Latest Release Crates.io AUR Language License

A fast, lightweight, and extremely customizable terminal file manager carved in Rust.

Full Configuration Guide • Installation Guide • Quick Start • General Settings • Theme Configuration • Key Bindings

  • Rich File Actions: Move, filter, copy, rename, tabs, and more, all with the keyboard.
  • Extremely Customizable: Tweak keybindings, colors, and layout via TOML.
  • Blazing Fast: Instant navigation, even in huge directory trees.
  • Minimal Dependencies: Only the essential crates; advanced features are opt-in.
  • Cross-Platform: Works on Linux, macOS, and Windows.
  • Keyboard-Driven: Every action accessible by keybindings. No mouse needed.
  • Integrated Find (fd required): Blazingly fast file search.
  • Multi-threaded engine: Spawns 9 lightweight dedicated worker threads (with crossbeam_channel) for I/O, preview, find, and file operations, so UI is never blocked.
  • Essential-only Rust crates: No external TUI frameworks or bloat.
  • Direct terminal rendering: Uses ratatui & crossterm.
  • Optional blazing-fast find: Integrates with fd for recursive fuzzy search.
  • Blazingly lightweight: The rn binary is compact (typically 1.6-2 MB, depending on operating system and architecture).
  • Minimal memory footprint: Optimized for low RAM usage.

runa - rn is a minimalist terminal file manager focused on speed and simplicity.
It allows you to navigate directories, view file listings, and perform typical file browser actions.

runa is very customizable, checkout the Configuration docs for all the available options.

[!IMPORTANT] runa is a work in progress. It is being actively developed and features may change over time.

Changelog

For a detailed list of changes and release notes, see CHANGELOG.md.

Installation

Cargo:

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.

[!TIP] Checksum & Attestation Check:
All releases starting with v0.5.11 are immutable.
Each release includes a Release Attestation json file that verifies that the release is immutable.

You can verify the integrity of the release archives using the attestation verification with the GitHub CLI:

gh attestation verify --repo alexm-dev/runa <file_name>

You can also verify the integrity of the release archives using the SHA256SUMS.txt file in the Release page.

Unix

sha256sum -c SHA256SUMS.txt

This checks all the checksums of the SHA256SUMS.txt. To check a specific release archive:

grep runa-linux-x86_64.tar.gz SHA256SUMS.txt | sha256sum -c

Windows

Get-FileHash runa-windows-x86_64.zip -Algorithm SHA256

Compare the output with the corresponding entry in SHA256SUMS.txt.

Build from source

Clone the repo and build with Cargo:

git clone https://github.com/alexm-dev/runa.git

cd runa

cargo build --release

Usage

After installation, start runa with: rn

[!TIP] Icons (for files, folders, etc.) are disabled by default, but can be enabled in your runa.toml.
To display them correctly, use a Nerd Font or a patched font in your terminal.
Without a Nerd Font, icons may appear incorrectly and the UI may not render as intended.

Optional Enhancements

runa is designed to be lightweight and standalone. However, some advanced features leverage specialized external tools:

  • Fuzzy Search: To enable fast, recursive fuzzy finding, install fd.

    • If fd is detected in your PATH, the search feature will be enabled automatically.
    • Without it, runa remains a fully functional file manager but will notify you if you attempt a recursive search.
    • Also enables move_file auto-complete if fd is enabled.

  • Preview Syntax coloring: To enable syntax coloring in the preview pane, install bat

    • If bat is detected and installed, you can switch method in the runa.toml to method = "bat".
    • Without it, runa uses the internal preview method, which is a plain preview method useful for extra speed without syntax highlighting.

Configuration

By default, runa checks for configuration in these locations, in order:

  1. If the environment variable RUNA_CONFIG is set, its value is used as the config path.

  2. If XDG_CONFIG_HOME is set, runa looks for:

    $XDG_CONFIG_HOME/runa/runa.toml

  3. Otherwise, the fallback is:

    $HOME/.config/runa/runa.toml

    (On Windows, this means inside the user's config folder.)

Overriding the config path

You can explicitly set a custom config location by setting the environment variable RUNA_CONFIG.

Example:

export RUNA_CONFIG=/path/to/your/runa.toml

You can generate a default config using the --init or --init-full flag:

rn --init


# For the whole configuration options runa.toml

rn --init-full


# For help with all the configuration options.

rn --config-help

This will generate a config in the default config path.

Roadmap

runa is in active development, with future releases focusing on expanding functionality while keeping it fast and lightweight.

Planned Features

  • Image Previews: Support for Sixel/Kitty graphics protocols

Completed Features

  • Tabs: Spawn and manage multiple tabs of runa
  • Syntax Highlighting: bat integration for the preview pane
  • Search & Discovery: Integrated fuzzy finding (fd support)
  • File Operations: Copy, move, delete, and rename from within the UI
  • Content Search: Text search and filtering
  • Performance: Reactive rendering
  • UI Customization: Pane-specific styling and Hex color support
  • Navigation Context: Persistent Parent (Origin) and Preview panes

See CHANGELOG.md for version details and release history.

Support & Contribute

If you enjoy using runa, you can help the project grow:

  • ⭐ Star the Repo: It helps more people discover runa :)
  • 🐛 Report Bugs: Open an issue if something doesn't work as expected.
  • 💡 Feature Requests: Suggest new ideas in the Discussions tab.
  • 🦀 Contribute: Pull requests are always welcome! Checkout the CONTRIBUTING guide for more info.

Special Thanks

Many thanks to @lmartinez-mirror, the maintainer of runa-bin, for maintaining the binary AUR package.

Many thanks to @sharkdp for fd and bat, excellent CLI tools runa integrates with for fuzzy finding and syntax preview.

Credits & Ecosystem

runa stands on the shoulders of these incredible Rust crates:

  • Terminal UI:
    • Ratatui: Direct, fast terminal rendering.
    • Crossterm: Cross-platform terminal I/O.
  • Configuration:
    • Serde: Data serialization/deserialization.
    • toml-rs: TOML parsing.
  • Concurrency:
  • Optional Integrations:
    • fd: High-performance fuzzy finder (search enhancement).
    • bat: Syntax-highlighted file previews.

License

This project is dual licensed under the MIT OR Apache-2.0 license.

See the LICENSE-MIT and LICENSE-APACHE files for details.