bibleit 0.5.2

Interactive Bible Reading

bibleit

Interactive Bible reading for the terminal, plus a lightweight live web viewer, built with Python, Textual, and libbibleit.

Features

• Terminal Bible reader with keyboard-first navigation.
• Multiple translations open side by side or stacked vertically.
• Synchronized cursor across open translation panes.
• Go-to navigation with g or @, supporting verse, chapter/verse, and fuzzy book names.
• Text Find with Ctrl+F, result browsing, and visual translation toggles.
• Strong's references with linked entries via Ctrl+G.
• Live web viewer for sharing the active verse with viewers.
• Live viewer controls for light/dark theme, font size, presentation mode, and translation selection.
• Persistent local config for live URL/token and theme.
• Docker and Fly.io deployment support.

Requirements

• Python 3.11+
• GNU Make

Installation

Clone the repository:

git clone https://github.com/mittel-labs/bibleit.git
cd bibleit/python

Install development dependencies:

make install

Install the package locally:

make local-install-test

Usage

Run the terminal application:

make run

Run the live web viewer:

make live

Then open:

http://localhost:8000

Run the installed package directly:

python -m bibleit

Read a verse from the command line:

bibleit -t NVIPT dani 9.2
python -m bibleit -t KJV "john 3:16"
python -m bibleit -t NVIPT,KJV dani 9:2-15
bibleit -t KJV --strongs genesis 1.1

With no arguments, bibleit and python -m bibleit open the terminal app. With a reference, they print matching verse text to stdout. Set a default translation with BIBLEIT_DEFAULT_TRANSLATION, BIBLEIT_TRANSLATION, or DEFAULT_TRANSLATION in ~/.bibleit/config.

Keyboard

Shortcut	Action
↑ / ↓	Previous / next verse
g / G / @	Go to verse, chapter, or book reference
Tab / Shift+Tab	Next / previous open translation
Tab in Go To	Cycle go-to matches
Ctrl+F	Find verse text
← / → in Find	Switch Find translation
Ctrl+T	Open translations
Ctrl+G	Toggle Strong's
Ctrl+H	Open history
Ctrl+A / Ctrl+E	Beginning / end of current chapter
< / >	Previous / next chapter
Ctrl+W	Close the active translation pane
Ctrl+M	Maximize / restore the active translation pane
Ctrl+Tab	Rotate translations
Ctrl+1-Ctrl+9	Select a translation while maximized
Esc	Restore panes when a translation is maximized
F2	Toggle split layout
Ctrl+L	Toggle live mode
Ctrl+D	Toggle theme
Ctrl+P	Open config
?	Show shortcuts

At startup bibleit shows a small welcome screen with the most useful shortcuts. Press any shortcut to dismiss it and continue.

Configuration

bibleit reads configuration from ~/.bibleit/config as TOML. Environment variables with the BIBLEIT_ prefix take precedence.

Config	Environment variable	Description
LIVE_URL	BIBLEIT_LIVE_URL	Live server URL used by the terminal app
LIVE_TOKEN	BIBLEIT_LIVE_TOKEN	Optional token used to protect live control requests
DEFAULT_TRANSLATION	BIBLEIT_DEFAULT_TRANSLATION	Default translation slug for CLI verse lookup
THEME	BIBLEIT_THEME	light or dark

Open the config screen with Ctrl+P.

Example:

LIVE_URL = "https://bibleit.example.com"
THEME = "dark"

Empty values are not written to the config file.

Live Mode

Start the live web server:

make live

Run the terminal app and point it at the live server:

BIBLEIT_LIVE_URL=http://localhost:8000 make run

Press Ctrl+L in the terminal app to publish the active verse to the web viewer. When live mode is off, the browser shows a waiting splash screen.

Development

Run with Textual development tools:

make run-dev

Open a Python shell inside the virtual environment:

make shell

Run tests:

make test

Run lint:

make lint

Format code:

make lint-fix

Build distribution packages:

make build

bibleit package versions are derived from Git tags via hatch-vcs. To publish a release, create a tag such as v0.5.1 and build from that tag instead of editing pyproject.toml.

Install local wheel:

make install-local

Run the local installation test:

make local-install-test

Live server configuration

The live server supports the following environment variables:

Variable	Default	Description
BIBLEIT_LIVE_HOST	0.0.0.0	Bind address
BIBLEIT_LIVE_PORT	8000	Server port
BIBLEIT_LIVE_URL	unset	Public live server URL used by the terminal app
BIBLEIT_LIVE_TOKEN	unset	Optional token used to protect live control requests
BIBLEIT_LIVE_TITLE	bibleit live	Browser page title
BIBLEIT_FIND_INDEX_CACHE_SIZE	4	Max number of translation text indexes cached by Find

Example:

export BIBLEIT_LIVE_HOST=0.0.0.0
export BIBLEIT_LIVE_PORT=8000
export BIBLEIT_LIVE_URL=http://localhost:8000

make live

Docker

Build the image:

docker build -t bibleit .

Run terminal mode:

docker run -it bibleit

Run live web mode:

docker run -p 8000:8000 bibleit live

Then open:

http://localhost:8000