󰀂 Porthole

A fancy TUI file chooser for your terminal, built with Ratatui.

Porthole provides an interactive, keyboard-driven file browsing experience with Nerd Font icons, a preview panel, bookmarks sidebar, and multi-select support. It outputs selected file paths to stdout — making it easy to integrate into scripts, editors, and custom workflows.

• Vim-like navigation — j/k to move, h to go back, l/Enter to enter
• Bookmarks sidebar — quick access to Home, Downloads, Documents, Pictures, Desktop, Root
• File preview panel — shows file type, size, modification time
• Search/filter — press / to filter files by name
• Multi-select — Tab to toggle selection, -m flag to enable multi-select mode
• Open files — press o to open with system default app, or use --open flag
• Hidden files toggle — press . to show/hide dotfiles
• Nerd Font icons — contextual icons for 20+ file types
• Catppuccin-inspired theme — easy on the eyes

git clone https://github.com/ai-pivot/porthole.git
cd porthole
cargo build --release

The binary will be at target/release/porthole.

# Browse current directory
porthole

# Start from a specific directory
porthole -d ~/Downloads

# Select multiple files
porthole -m

# Show hidden files
porthole -a

porthole -t "Choose a config file"

# Select a file and open it automatically after exit
porthole --open

Or press o inside the TUI to open the current file without exiting.

porthole -o selected.txt

# Open selected file in vim
vim "$(porthole)"

# Copy selected files
cp $(porthole -m) /destination/

Usage: porthole [OPTIONS]

Options:
  -d, --directory <DIR>      Starting directory
  -t, --title <TITLE>        Dialog title
  -m, --multi                Allow multiple file selection
  -o, --output <FILE>        Save selection to file instead of stdout
  -f, --filter <PATTERN>     File filter pattern (e.g. "*.rs,*.toml")
  -a, --all                  Show hidden files
  -O, --open                 Open selected file with system default app after exit
  -h, --help                 Show help
  -V, --version              Show version

• ratatui — TUI framework
• crossterm — Terminal manipulation
• clap — CLI argument parsing
• open — Cross-platform file opening
• dirs — Standard directory paths
• chrono — Time formatting
• unicode-width — Unicode character width

MIT