A distraction-free terminal EPUB reader. Opens a single book or a whole directory; remembers where you left off; never gets in your way.
── Frankenstein ─ Ch 4/24 ─ Page 18/247 ─ q quit ──
Homebrew (macOS, Linux):
brew install aqiulc/cleader/cleaderOr brew tap aqiulc/cleader once, then brew install cleader.
With Rust (any platform):
cargo install cleaderThe cleader binary lands in ~/.cargo/bin/. Make sure that's on your $PATH.
Prebuilt binaries (no Rust required) — download from the latest GitHub Release:
| Platform | Asset |
|---|---|
| Linux x86_64 | cleader-x86_64-unknown-linux-gnu.tar.gz |
| Linux ARM64 (Raspberry Pi, Graviton) | cleader-aarch64-unknown-linux-gnu.tar.gz |
| macOS Apple Silicon (M1/M2/M3/M4) | cleader-aarch64-apple-darwin.tar.gz |
| Windows x86_64 | cleader-x86_64-pc-windows-msvc.zip |
Extract and move the cleader binary somewhere on your $PATH. Intel
Mac users — cargo install cleader works; a prebuilt Intel binary
will land in a follow-up release.
From source:
git clone https://github.com/aqiulc/cleader
cd cleader
cargo install --path .Read a single book:
cleader path/to/book.epubBrowse a directory of books:
cleader path/to/library/The directory form opens a library view where you can pick a book.
Toggle between grid (with ASCII cover art) and list views with g.
Search by title or author with /.
-w,--width=N— target body text width in columns (default 80).--help/--version— standard clap.
Press ? from anywhere for the full overlay. Quick reference:
Library
| Action | Keys |
|---|---|
| Navigate | ↑ ↓ ← → or h j k l |
| Toggle grid/list | g |
| Search | / |
| Open selected book | Enter |
Reading
| Action | Keys |
|---|---|
| Scroll line | ↑ ↓ or k j |
| Flip page | ← → or h l or Space b or PgUp PgDn |
| Next / previous chapter | n / N (Shift+n) |
| Table of contents | t |
Anywhere
| Action | Keys |
|---|---|
| Toggle help overlay | ? |
| Quit (saves position) | q, Esc, or Ctrl+C |
Reading positions, view preferences, and cached cover art live in the OS-native data directory:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/cleader/ |
| Linux | ~/.local/share/cleader/ |
| Windows | %APPDATA%\cleader\ |
Three files plus a directory:
registry.json— reading positions (one entry per book, content-hashed)prefs.json— view-mode preferencecovers/v5/— cached cover ASCII art (one file per book)
All are safe to delete; cleader will start fresh. Books are identified by SHA-256 of their content, so moving an EPUB doesn't reset your progress.
- Smart resize — wrap width changes preserve your position in the source text, not just the line offset.
- Atomic saves — reading position writes go through a tempfile+rename, so a crash mid-write never corrupts the registry.
- Background cover rendering — the library worker generates covers viewport-only and caches them to disk; second-open is instant.
- Cross-platform — one binary, one code path. macOS, Linux, Windows.
Dual-licensed:
at your option. Contributions are accepted under the same dual license.
Created by Aqiul — aqiul.c@gmail.com.