# vfv (Vive File Viewer)
[日本語](README_ja.md)
**The ultra-lightweight terminal file viewer for vibe coding.**
When you're in the flow with AI pair programming, you just want to quickly browse and check files—no complex setup, no heavy features. Just open, search, view, and get back to coding.
[](https://github.com/noumi0k/vive-file-viewer/actions/workflows/ci.yml)
[](https://crates.io/crates/vfv)
https://github.com/user-attachments/assets/e3ec4515-ac0d-453f-851f-ca449b19e877
## Why vfv?
- **Zero config fuzzy search** - Built-in [nucleo](https://github.com/helix-editor/nucleo) (same as Helix editor). No fzf setup needed.
- **3MB single binary** - Install and run. That's it.
- **Vim keybindings** - Navigate like you're used to.
- **Syntax highlighting** - Preview code with colors.
- **.gitignore aware** - Powered by ripgrep's ignore crate.
### Not for you if...
You need file management (copy, move, delete), image preview, or plugin ecosystem. Use [yazi](https://github.com/sxyazi/yazi) instead.
## Install
```bash
cargo install vfv
```
Or download pre-built binary from [Releases](https://github.com/noumi0k/vive-file-viewer/releases).
<details>
<summary>Build from source</summary>
```bash
git clone https://github.com/noumi0k/vive-file-viewer.git
cd vive-file-viewer
cargo install --path .
```
</details>
## Setup
Run the setup command to configure everything automatically:
```bash
vfv init
```
This will:
- Create config file
- Install shell completions (zsh/bash/fish)
- Install man page
- Update your shell rc file
Supported shells: **zsh**, **bash**, **fish**
Use `--force` to overwrite existing files.
### Config File
Location:
- **macOS**: `~/Library/Application Support/vive-file-viewer/config.toml`
- **Linux**: `~/.config/vive-file-viewer/config.toml`
- **Windows**: `%APPDATA%\vive-file-viewer\config.toml`
```toml
# Editor command
editor = "vim"
editor_args = []
# Show hidden files by default
show_hidden = false
# Maximum lines to preview
preview_max_lines = 1000
# Syntax highlighting theme
# Options: "base16-ocean.dark", "base16-eighties.dark",
# "base16-mocha.dark", "Solarized (dark)", "Solarized (light)"
theme = "base16-ocean.dark"
```
## Usage
```bash
vfv # Browse current directory (TUI)
vfv ~/projects # Browse specific directory (TUI)
```
## Keybindings
Press `?` to show help screen.
### File Browser
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `Enter` / `l` | Open file / Enter directory |
| `h` / `Backspace` | Go to parent directory |
| `g` | Go to top |
| `G` | Go to bottom |
| `e` | Open in editor |
| `y` | Copy path to clipboard |
| `f` + char | Jump to entry starting with char |
| `;` | Jump to next match |
| `,` | Jump to previous match |
| `/` | Search (with options) |
| `.` | Toggle hidden files |
| `r` | Reload |
| `?` | Show help |
| `q` | Quit |
### File Preview
| `j` / `↓` | Scroll down |
| `k` / `↑` | Scroll up |
| `Ctrl+d` | Half page down |
| `Ctrl+u` | Half page up |
| `Ctrl+f` / `PageDown` | Page down |
| `Ctrl+b` / `PageUp` | Page up |
| `g` | Go to top |
| `G` | Go to bottom |
| `e` | Open in editor |
| `h` / `q` | Back to file browser |
### Search
Press `/` to open search. You can use options like CLI:
```
main.rs # Fuzzy search
config -e # Exact match
src/main -d # Directories only, path matching
telemo -d -e # Directories only + exact match
main -b ~/dev # Search from specific base directory
```
| (type) | Enter query and options |
| `Enter` | Execute search |
| `Esc` | Cancel |
### Search Results
| `j` / `k` / `Tab` | Select result |
| `Enter` | Open selected |
| `/` | New search |
| `Esc` | Cancel |
## CLI Search
Search files directly from the command line. Designed to be called from AI assistants or shell scripts.
```bash
vfv find <query> [path] # Fuzzy search files/directories
```
### Options
| `-d, --dir` | Search directories only |
| `-e, --exact` | Exact match (no fuzzy) |
| `-n, --limit <N>` | Maximum results (default: 20) |
| `-1, --first` | Output only the top result |
| `-j, --json` | Output as JSON |
| `-c, --compact` | Compact JSON (single line) |
| `-t, --timeout <SEC>` | Timeout in seconds (default: 0 = no limit) |
| `-q, --quiet` | No spinner (for scripts/AI) |
### Path Matching
When query contains `/`, it matches against the full path:
```bash
vfv find "src/main" ~/dev # Matches paths containing "src/*/main*"
vfv find "main" ~/dev # Matches filename only
```
### Examples
```bash
# Basic search
vfv find "config" ~/dev
# Find a directory and cd into it
cd $(vfv find "project" ~/dev -d -1 -q)
# Path search: find "telemo" under any "dev" directory
vfv find "dev/telemo" ~ -d
# Exact match
vfv find "config" ~/dev -e
# AI-friendly: quiet, compact JSON, with timeout
vfv find "main" ~/dev -q -j -c -t 5
```
### Exit Codes
| 0 | Results found |
| 1 | No results |
| 124 | Timeout |
## License
MIT