fileview 0.9.1

A minimal file tree UI for terminal emulators
Documentation

FileView (fv)

Crates.io License: MIT

A minimal, VSCode-style file tree TUI for modern terminal emulators.

English | 日本語

Features

  • Fast file tree navigation with vim-like keybindings
  • Git integration - color-coded file status and branch display
  • Multi-select support for batch operations
  • Preview panel with support for:
    • Text files (syntax highlighting by extension)
    • Images (Kitty/iTerm2/Sixel protocols with auto-detection)
    • Directories (file count, size statistics)
    • Binary files (hex dump view)
  • Copy/cut/paste with internal clipboard
  • System clipboard integration (path/filename copy)
  • Pick mode for external tool integration
  • Callback execution on file selection
  • Hidden files toggle
  • Mouse support (click, double-click, scroll, drag-and-drop)
  • Nerd Fonts icons (optional, enable with --icons)

Git Status Colors

When inside a git repository, files are color-coded by their status:

Color Status
Yellow Modified
Green Added / Untracked
Red Deleted
Cyan Renamed
Gray Ignored
Magenta Conflict

The current branch name is displayed in the status bar.

Image Preview

FileView automatically detects your terminal and selects the optimal image protocol:

Terminal Protocol Quality
Kitty Kitty Graphics Highest
Ghostty Kitty Graphics Highest
Konsole Kitty Graphics Highest
iTerm2 iTerm2 Inline Highest
WezTerm iTerm2 Inline Highest
Warp iTerm2 Inline Highest
Foot Sixel Good
Windows Terminal Sixel Good
VS Code Halfblocks Basic
Alacritty Halfblocks Basic
Other Auto-detect Varies

Override with FILEVIEW_IMAGE_PROTOCOL environment variable (see below).

Installation

From crates.io (Recommended)

cargo install fileview

With Chafa support (optional)

For better image quality on terminals without native image protocol support:

# Install libchafa first
# macOS:
brew install chafa

# Ubuntu/Debian:
sudo apt install libchafa-dev

# Then install with chafa feature
cargo install fileview --features chafa

From source

git clone https://github.com/Hiro-Chiba/fileview.git
cd fileview
cargo install --path .

# Or with chafa:
cargo install --path . --features chafa

Requirements

  • Rust 1.70+
  • A terminal with true color support (recommended: Ghostty, iTerm2, Alacritty)

Usage

# Open current directory
fv

# Open specific directory
fv /path/to/directory

# Pick mode (output selected path to stdout)
fv --pick

# Pick mode with JSON output
fv --pick --format json

# Execute command on selection
fv --on-select "code {path}"

Keybindings

Navigation

Key Action
j / ↓ Move down
k / ↑ Move up
g Go to top
G Go to bottom

Tree Operations

Key Action
l / → / Tab Expand directory
h / ← / Backspace Collapse directory
Enter Toggle expand/collapse
H Collapse all
L Expand all (depth limit: 5)

Selection

Key Action
Space Toggle mark
Esc Clear all marks

File Operations

Key Action
a Create new file
A Create new directory
r Rename
D / Delete Delete (with confirmation)
y Copy to clipboard
d Cut to clipboard
p Paste

Search

Key Action
/ Start search
n Next search result

Preview

Key Action
P Toggle side preview panel
o Open fullscreen preview
Tab Toggle focus between tree and preview (when preview visible)

Side Preview Focus Mode

When the side preview panel is open, press Tab to switch focus:

Focus j/k/↑/↓ g/G b/f
Tree Navigate files Top/Bottom of list -
Preview Scroll content Top/Bottom of preview Page scroll
  • Click on a panel to switch focus
  • Scroll wheel works on the focused panel
  • Esc returns focus to tree
  • Focused panel has cyan border highlight

Other

Key Action
. Toggle hidden files
R / F5 Refresh
c Copy path to system clipboard
C Copy filename to system clipboard
? Show help
q Quit

CLI Options

Option Description
-p, --pick Pick mode: output selected path(s) to stdout
-f, --format FMT Output format: lines (default), null, json
--on-select CMD Run command when file is selected
-i, --icons Enable Nerd Fonts icons (default)
--no-icons Disable icons
-h, --help Show help
-V, --version Show version

Environment Variables

Variable Description
FILEVIEW_ICONS=0 Disable icons by default
FILEVIEW_IMAGE_PROTOCOL Force image protocol: auto, halfblocks, chafa, sixel, kitty, iterm2

Placeholders for --on-select

Placeholder Description
{path} Full path
{dir} Parent directory
{name} Filename with extension
{stem} Filename without extension
{ext} Extension only

Examples

# Use as file picker for another tool
selected=$(fv --pick)
echo "Selected: $selected"

# Open selected file in editor
fv --on-select "vim {path}"

# Copy selected file path to clipboard (macOS)
fv --on-select "echo {path} | pbcopy"

# Multiple file selection with JSON output
fv --pick --format json

License

MIT