output.mp4
- Fuzzy File Search: Interactive file picker with fuzzy search to quickly find your PDFs and EPUBs
- Smart Content Detection: Automatically detects and displays text, images, or mixed content pages
- High-Resolution Image Rendering: Uses terminal graphics protocols (Sixel/Kitty/iTerm2) for crisp image display
- Render Cache and Prefetch: Caches rendered pages and prepares neighboring pages in the background
- Half Page View: Supports screen splitting to display half pages at high quality
- Image Invert: Inverts the Image while preserving the core colors of the image.
- HiDPI/Retina Support: Dynamic cell size detection for sharp rendering on high-DPI displays
- Auto-Reload: Automatically reloads when the PDF changes (perfect for LaTeX compilation with
latexmk -pvc) - Fit Modes: Toggle between height-fit, width-fit, and auto-fit modes
- Manual Zoom: Adjust zoom from 10% to 200%
- In-Document Search: Search for text within documents
- Navigation Tools: Follow document links, browse jump history, and fuzzy-search the table of contents
- Viewer Control: Inspect and control running viewers with
dvctlorpdf-cli ctl - Intelligent Text Reflow: Automatically reformats text to fit your terminal width while preserving paragraphs
- Terminal-Aware: Detects your terminal type and optimizes rendering accordingly
- Multiple Formats: Supports PDF, EPUB, DOCX, HTML, PNG, and JPEG files
| Key | Action |
|---|---|
j / Space / Down / Right |
Next page |
k / Up / Left |
Previous page |
g |
Go to specific page |
T |
Table of contents overlay (fuzzy search, Enter jumps) |
Ctrl+Click |
Follow links, references, citations, and URLs |
Cmd+Left / Cmd+Right |
Move backward or forward through jump history |
b |
Back to file picker |
/ |
Search in document |
n |
Next search result |
N |
Previous search result |
t |
Toggle text/image/auto mode |
f |
Cycle fit modes (height/width/auto) |
D |
Cycle page tint (white/gray/dark/invert) |
+ / = |
Zoom in |
- |
Zoom out |
r |
Refresh display (re-detect cell size) |
d |
Show debug info |
h |
Show help |
q |
Quit |
2 |
Cycle page modes |
in your configuration.nix file add pdf-cli
environment.systemPackages = with pkgs; [
pdf-cli
];Using yay
yay -S pdf-cliUsing paru
paru -S pdf-cli
# Clone this repository
git clone https://github.com/Yujonpradhananga/pdf-cli
# Install dependencies
go mod tidy
# Build
go build -o pdf-cli .
# Optionally move to your PATH
mv pdf-cli ~/local/bin/
# Or build and install pdf-cli plus the dvctl symlink
make install# Search current directory (default)
pdf-cli
# Search specific directory
pdf-cli ~/Documents/papers/
# Open a specific file directly
pdf-cli paper.pdf
# Inspect a running viewer
pdf-cli ctl statusThe auto-reload feature makes this viewer ideal for LaTeX editing:
- Open your PDF:
pdf-cli paper.pdf - Run LaTeX compiler in another terminal:
latexmk -pvc paper.tex - The viewer automatically reloads when the PDF updates, preserving your page position
The viewer handles partially-written PDFs gracefully, waiting for the file to stabilize before reloading.
- Go 1.21+
- go-fitz - PDF/EPUB parsing (MuPDF)
- go-termimg - Terminal image rendering
- fuzzy - Fuzzy search
- golang.org/x/term - Terminal control
Optimized for terminals with graphics support:
- Kitty (recommended) - Native cell size detection via escape sequences
- Foot
- WezTerm
- iTerm2
- Alacritty
- xterm (with Sixel support)
Works in any terminal, but image rendering quality depends on terminal capabilities.
The reader scans the current directory (or specified directory) for supported documents and images. Use the fuzzy search to quickly filter and select a file. The viewer intelligently detects whether document pages contain text, images, or both, and renders them appropriately for terminal display.
PDFs are rendered as images by default (essential for math, diagrams, and formatted content) at a DPI calculated to match your terminal's pixel dimensions for optimal sharpness.
MIT