Basic Usage

View a PDF file in your terminal:

gtpv document.pdf

Start on Specific Page

gtpv document.pdf -p 5

Force Output Format

# Force text mode (works in any terminal)
gtpv document.pdf -f halfblock

# Force Kitty graphics protocol
gtpv document.pdf -f kitty

# Force braille art (monochrome)
gtpv document.pdf -f braille

Custom DPI

# Higher quality (default is 150)
gtpv document.pdf --dpi 300

# Lower quality, faster rendering
gtpv document.pdf --dpi 72

view (default)

Interactive PDF viewer with keyboard navigation.

gtpv view document.pdf
gtpv document.pdf  # same as above

render

Render specific page(s) to terminal output.

# Render page 5
gtpv render document.pdf --page 5

# Render multiple pages
gtpv render document.pdf -p 1 -p 2 -p 3

# Output to PNG file
gtpv render document.pdf --page 1 --output page1.png

info

Display PDF metadata and page information.

# Human-readable output
gtpv info document.pdf

# JSON output for scripting
gtpv info document.pdf --json

stream

Start stream mode for editor integration (Neovim, etc.).

gtpv stream document.pdf

Graphics Protocols (Best Quality)

FORMAT	TERMINALS	QUALITY
kitty	Kitty, WezTerm, Ghostty	Excellent
iterm2	iTerm2	Excellent
sixel	foot, mlterm, Contour, mintty	Very Good

Text Fallback (Universal)

FORMAT	COLORS	BEST FOR
halfblock	Truecolor/256	General use, color PDFs
braille	Monochrome	Diagrams, line art
block	Grayscale	Maximum compatibility

Auto-Detection

By default (-f auto), GTPV auto-detects the best format:

1. Check $TERM and $TERM_PROGRAM
2. Query terminal capabilities via escape sequences
3. Fall back to halfblock text mode

Stream mode provides a stdin/stdout protocol for editor integration.

Start Stream Mode

gtpv stream document.pdf

Commands

COMMAND	DESCRIPTION
goto <N>	Navigate to page N
render	Render current page to stdout
prefetch <START>-<END>	Preload pages into cache
evict <START>-<END>	Remove pages from cache
info	Print current state (JSON)
quit	Exit stream mode

Neovim Integration Example

-- Neovim Lua example
local job = vim.fn.jobstart({'gtpv', 'stream', pdf_path}, {
  on_stdout = function(_, data)
    -- Handle rendered output
  end
})

-- Navigate to page 5
vim.fn.chansend(job, 'goto 5\n')
vim.fn.chansend(job, 'render\n')

-- Preload next 10 pages in background
vim.fn.chansend(job, 'prefetch 6-15\n')

Benefits

• Single Process - One GTPV instance for all pages
• LRU Cache - ~30ms navigation for cached pages
• Memory Control - Explicit prefetch/evict
• Zero Temp Files - Direct terminal output

Examples

# Always use text mode (useful for SSH)
export GTPV_PROTOCOL=halfblock

# Force Kitty graphics
GTPV_PROTOCOL=kitty gtpv document.pdf

# Enable debug output
GTPV_DEBUG=1 gtpv document.pdf 2>debug.log

Project Structure

src/
├── main.rs          # CLI entry point
├── lib.rs           # Library exports
├── cli/             # Argument parsing (custom, zero deps)
├── pdf/             # PDF handling (PDFium wrapper)
│   └── document.rs  # PDF document abstraction
├── render/          # Rasterization and encoding
│   ├── engine.rs    # Rendering pipeline
│   └── formats/     # Output format implementations
├── protocol/        # Terminal graphics protocols
│   ├── kitty.rs     # Kitty graphics
│   ├── iterm2.rs    # iTerm2 inline images
│   ├── sixel.rs     # Sixel encoding
│   └── text/        # Text fallbacks
├── cache/           # LRU page cache
│   └── lru.rs       # Custom LRU implementation
├── stream/          # Stream API for editors
└── error.rs         # Error types (custom, zero deps)

Design Philosophy

• Zero Runtime Dependencies - Single static binary
• PDFium for PDF - Battle-tested rendering engine, statically linked
• Custom Everything Else - LRU cache, CLI parsing, JSON output, error handling
• Protocol Abstraction - Same API for Kitty, Sixel, text modes

Zero-Dependency Strategy

GTPV eliminates runtime dependencies through:

1. Custom CLI parser instead of clap
2. Custom LRU cache instead of lru crate
3. Custom JSON writer instead of serde_json
4. Custom error types instead of thiserror/anyhow
5. Bundled PDFium via pdfium-bind (extracted at runtime)

See ZERO_DEPENDENCY_STRATEGY.md for the complete roadmap.