lsv

A ls-visual TUI file browser with icon previews, built with ratatui and ratatui-image.

Renders directories and files as a grid of icon cards with labels, supports vim-style keybindings, mouse interaction, fuzzy search, and inline file/image preview.

Features

• Grid and list views — toggle between an icon grid and a compact list, switchable on the fly (Space v)
• Keyboard-first navigation — vim-style movement (h j k l, g/G), plus fuzzy search with n/N to step through matches
• Mouse support — click an entry to open it, scroll to move the cursor, and click any segment of the path in the title bar to jump straight to that directory
• Leader key menu — press Space to pop up a which-key-style tray for every command: search, toggle preview, toggle grid/list, toggle hidden files, copy path, create directory, rename, delete (with confirmation), and yank/cut/paste
• File management — create directories, rename and delete entries, and copy/cut/paste files and directories, all from the keyboard
• Inline preview — toggle a preview pane for files and images without leaving the browser
• Bookmarks and recent directories — mark favorite directories with B and jump back to them or to recently visited directories from the leader menu (Space b / Space g), both persisted across restarts
• Customization — persistent settings for icon size (Small/Medium/Large), view mode (Grid/List), and sort order (Name/Size/Modified), editable from the in-app settings screen or config.toml

Requirements

• Rust 1.85+ (edition 2024)
• A terminal with image protocol support (iTerm2, Kitty, WezTerm, etc.) for icons and image preview. Falls back to halfblocks on unsupported terminals. A Nerd Font is embedded in the binary for glyph rendering — no external Nerd Font installation required.

Install

Homebrew (macOS/Linux)

brew install thenickygee/tap/lsv

Shell script (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/thenickygee/lsv/releases/latest/download/lsv-installer.sh | sh

From source

git clone https://github.com/thenickygee/lsv.git
cd lsv
cargo install --path .

Usage

lsv              # browse current directory
lsv <path>       # browse a specific directory

Keybindings

Navigation stays direct, vim-style. Everything else lives behind the Space leader key, which pops up a tray of the available commands (like which-key in Neovim) — press Space then the key shown.

Key	Action
h / ←	Go to parent directory
l / → / Enter	Enter directory
j / ↓	Move cursor down
k / ↑	Move cursor up
g	Jump to first entry
G	Jump to last entry
n / N	Next / previous search match
B	Toggle bookmark on current directory
Esc	Quit
Mouse click	Enter directory
Mouse scroll	Move cursor

Leader commands (Space then...)

Key	Action
/	Start search
p	Toggle preview pane
s	Open settings
v	Toggle grid/list view
.	Toggle hidden files
c	Copy selected path to clipboard
a	Create new directory
r	Rename selected entry
d	Delete selected entry (with confirmation)
y / x / P	Yank copy / yank cut / paste
b	Open bookmarks picker
g	Open recent-directories picker
q	Quit

Configuration

Settings are stored in ~/.config/lsv/config.toml (or $XDG_CONFIG_HOME/lsv/config.toml). The file is created automatically when you change a setting in the settings screen.

icon_size = "Large"   # "Small", "Medium", or "Large"
view_mode = "List"    # "Grid" or "List"
sort_by = "Size"       # "Name", "Size", or "Modified"

License

MIT. The embedded Hack Nerd Font (assets/hack-nerd-font.ttf) is licensed under the Hack Open Font License / SIL OFL 1.1.