bible

A beautiful, fast TUI Bible reader for the terminal — 200+ languages, 1000+ translations, all downloaded on demand from the Beblia Holy-Bible-XML-Format repository. No texts are embedded in the binary.

Install

cargo install bible

Then:

bible

On first run the reader has no translations. Press i to install English KJV straight away, or T to browse the full catalog. You can also install from the shell:

bible install kjv

Screenshots

Reader with focus cursor + chapter pane:

Live-preview Settings modal (typography, theme, parallel divider):

Substring search across the whole text:

Bible-in-a-Year plan, full-year view:

Help overlay (?):

Highlights

• Verse cursor with ↑/↓, viewport scrolls only when the cursor leaves the visible area; mild bg highlight is always on so you can't lose the focus.
• Substring search with /, jumps between hits with n/N, multilingual.
• Reference jumps with :John 3:16 (also Jn 3,16 and other forms, any installed language).
• Bookmarks with multi-line notes: b for chapter, :b 16 note opens a split-pane editor while you keep reading the chapter on the left.
• Bible-in-a-Year reading plan generated for the current year on launch; p jumps to today and marks it done; P opens the full-year list.
• Parallel view (|) with two installed translations side-by-side, scroll-locked by verse.
• Settings modal (,) with live preview — typography, theme presets, width cap, parallel divider, justify, per-script letter padding.
• Bookmarks, settings, reading state, plan progress all in human-editable TOML under your platform's config directory.

Canonical reference handling (parsing John 3:16, validating chapters/verses, multilingual references) is delegated to the bibleref crate.

Use as a TUI

bible                       # launches the TUI when stdout is a TTY

Keybindings (Reader)

Vim-style fallbacks (hjkl, gg/G, H/L, Ctrl-d/Ctrl-u) are also wired up silently for muscle memory; the arrow keys above are the documented surface.

:b extensions on the jump bar:

The note editor is a split-pane view: chapter on the left, editor on the right. Tab toggles which pane has the keyboard, so you can scroll the chapter for context while writing.

:y extensions for copying to the clipboard:

The clipboard payload is the verse text plus an attribution line: "<text>\n\n— Book Chap:Verse (Translation)".

Bookmarks (B)

The list shows the first line of each note plus a (N lines) badge if there's more; the full note of the selected bookmark renders in a preview pane below the list.

Translation Manager

The filter is always focused — every letter you type feeds it, so names like "James" or "Jeremiah" filter cleanly. Commands use arrow keys plus modifier-keyed letters.

Reading plan (p / P)

A "Bible in a Year" plan is generated for the current year on launch — 1189 chapters split across 365 (or 366) days in canonical order. The top-right of the reader's title bar always shows today's reading, e.g. 📖 Today: Gen 14-15, Exo 1.

In the plan view:

Progress lives in <config>/plan.toml. The plan content itself is deterministic from the year alone, so only progress is persisted; on year change (Jan 1) the file is regenerated and last year's progress is discarded.

Settings (,)

A live-preview modal: the chapter pane stays visible on the left while you adjust settings on the right.

What's tunable:

• Typography — justify text (on by default), word padding, verse spacing, line spacing, verse-number style (inline-bold / superscript / hidden).
• Letter padding (per script) — extra cells around each grapheme for Tamil, Devanagari, Arabic, Hebrew, CJK, plus a default for any other non-Latin script. Workaround for terminal fonts that overlap glyphs.
• Theme — default, solarized-dark, high-contrast.
• Reader — max-columns cap (centres the pane on wide terminals), default translation on startup.
• Parallel — divider style between panes (single / double / none).

Settings are saved to <config_dir>/settings.toml on close. The file is human-editable TOML and schema-versioned.

Resume

The reader remembers your last position (translation, book, chapter, scroll, and parallel-view state) and restores it on the next launch. Stored in <config_dir>/state.toml.

Use as a CLI

When stdout is not a TTY (piped/redirected), or when a subcommand is given, bible runs headlessly:

bible read "John 3:16"
bible read "Acts 2"
bible search "Jesus"
bible list                 # installed
bible list --available     # downloadable (after `bible refresh`)
bible install kjv
bible uninstall kjv
bible refresh              # pull the full catalog from GitHub once

Pass --translation <id> to target a specific translation when several are installed.

Use as a library

use bible::{Bible, reference};

fn main() -> bible::Result<()> {
    let bible = Bible::load("EnglishKJBible")?;

    // bibleref handles parsing of `John 3:16`, `Jn 3,16`, etc.
    let parsed = reference::parse("John 3:16")?;

    // Search the whole text (case-insensitive, diacritic-folded).
    let hits = bible.search_substring("love");
    println!("{} hits", hits.len());

    Ok(())
}

Where your data lives

bible keeps everything in two directories chosen by directories::ProjectDirs — a data directory for the heavy bible binaries, and a config directory for your light, hand-editable preferences and reading state. Nothing is written outside these two directories.

Platform paths

What's in each

Bible translations — <data>/translations/<id>/, one folder per installed translation. Each contains:

• bible.bin — the parsed Bible serialised with bincode
• meta.json — translation id, display name, language

Settings, bookmarks, and reading state — all under <config>/, hand-editable TOML, schema-versioned (on version mismatch the file is ignored and defaults are used; the file is never clobbered):

Not persisted — command history (: and / recall via ↑/↓), back/forward navigation history (Ctrl-O / Tab), and search results all live in memory only and reset between launches.

Limitations

• v1 supports the 66-book Protestant canon only. Apocryphal / deuterocanonical books shipped by some Beblia translations are dropped on import with a warning. Hybrid canon support is a planned follow-up.
• Reference ranges (John 3:16-18) parse but aren't fully wired into the reader yet.

Credit

Bible XML files come from Holy Bible XML Format by Andrey at Beblia. Reference parsing uses the bibleref crate.

Licence

GPL-2.0-or-later.