Lex

lex is the elegant bible terminal

A local-first Bible study terminal for reading, searching, studying, and exporting Scripture work.

Lex is a Python CLI that keeps Bible study fast and offline. It combines Scripture reading, interlinear study, Strong's and STEPBible lexicon notes, Treasury of Scripture Knowledge cross-references, dictionary/encyclopedia lookups, and historical Christian documents in one terminal tool.

lex study John 1:1
lex search covenant -major
lex web Romans 1:1

Current CLI: ./lex.py
Current version: 2.3.4

Highlights

Feature	What it does
Multiple Versions	Switch between ESV, KJV, KJV 1611, NASB 1995, Geneva 1587, Septuagint (LXX), and Vulgate.
Auto-Updates	Keep code and databases in sync with one command: lex update.
Scripture reading	Read a verse with context or a full chapter from the local Bible DB.
Study mode	Show verse context, source text, transliteration, interlinear rows, lexicon notes, and TSK links.
Scoped search	Search all Scripture, one book, a book range, or a canon section such as -major, -gospels, or -nt.
Verse web	Print a verse as the center point with ranked local cross-reference connections.
Exports	Save search pages and study packets as DOCX or PDF.
Creeds	Browse historical Christian documents by tradition and section.
Terminal themes	Auto-detect light/dark terminal backgrounds, with sticky manual overrides.
Local data	Runs against local SQLite/JSON data stores with no web request required for normal use.

Quick Start

Option 1: Homebrew (Recommended for macOS and Linux)

If you have Homebrew installed, you can install Lex directly from the official tap:

brew tap elcafe7/lex
brew install lex

Option 2: Pip (Python Package Manager)

Install Lex directly from GitHub using pip:

pip install git+https://github.com/elcafe7/lex.git

This will make the lex command available globally. On the first run, Lex will automatically download the required Bible databases (approx 280MB) to ~/bible-lexicon-data.

Option 3: Scoop (Windows)

If you use Scoop on Windows, you can install Lex from the custom bucket:

scoop bucket add lex https://github.com/elcafe7/scoop-lex
scoop install lex

Option 4: Manual Installation (Git)

Clone the repo into whatever folder you want Lex to live in:

git clone https://github.com/elcafe7/lex.git
cd lex

Install Python dependencies:

python3 -m pip install -r requirements.txt

Register the lex command:

chmod +x setup.sh
./setup.sh

Restart your terminal, or run source ~/.bashrc. Now you can run:

lex              # Open the dashboard
lex update       # Sync latest code and data
lex -v           # List supported bible versions
lex -B kj16 John 3:16  # Read from the original 1611 KJV

Bible Versions

Switch versions using the -B (Bible) flag:

ID	Version Name	Edition / Year
esv	English Standard Version	Default
kjv	King James Version	Oxford 1769
kj16	King James Version	Original 1611
nasb	New American Standard	1995 Edition
gen	Geneva Bible	1587 Edition
lxx	Septuagint	Rahlfs 1935 (Greek)
vulg	Clementine Vulgate	Latin

Example: lex -B lxx Genesis 1:1

Terminal Themes

Lex automatically chooses a light or dark terminal palette at launch. Detection uses common terminal/theme environment variables, COLORFGBG, Apple Terminal or iTerm profile backgrounds on macOS, GNOME/KDE theme settings on Linux, and then platform appearance as a fallback.

To force and remember a palette for future launches:

lex -light
lex -dark
lex -auto

The saved manual theme lives in ~/.lex_config.json. If you run lex -light or lex -dark, that choice sticks until you run lex -auto or choose the other theme. For a one-command override without changing the saved setting:

LEX_THEME=light lex John 3:16
LEX_THEME=dark lex search covenant

Set LEX_NO_COLOR=1 when you intentionally want plain, uncolored output.

The GitHub repo includes the runtime SQLite databases and the compact JSON bundle under runtime-data/, so normal install does not need a second data download step.

Reading

References are forgiving. Full names and common abbreviations both work:

lex read John 3:16
lex John 1
lex jn 1:1
lex rom 8:1
lex 2 jn 1:2

Move from the last opened passage:

lex --next
lex --prev

Study Mode

Study mode is the main workbench:

lex study John 1:1
lex study Genesis 1:1
lex John 3:16 -i

It renders:

• verse context
• Greek or Hebrew/Aramaic source text
• transliteration
• interlinear alignment
• Strong's and STEPBible-backed lexicon notes
• local TSK cross-references

In an interactive terminal, study mode ends with a compact action bar:

n / p  next or previous verse
r      read context
w      verse web
e      export
q      done

Exports are saved under:

~/Documents/lex_exports/studies

Lex tries to open exported files automatically after saving.

Search

Search starts with an exact phrase query. If that finds nothing, Lex falls back to an all-terms search.

lex search israel
lex search "kingdom of god"
lex search covenant --page 2
lex search covenant --limit 20

Limit search by book, book range, or group:

lex search covenant -jeremiah
lex search beast -daniel-revelation
lex search resurrection -nt
lex search covenant -major

Useful group scopes:

-ot                 -old-testament
-nt                 -new-testament
-law                -pentateuch        -torah
-history
-wisdom             -poetry
-major              -major-prophets
-minor              -minor-prophets
-prophets
-gospels
-epistles           -letters
-pauline
-general-epistles

Interactive search uses a compact action bar:

1-10   study result
r #    read result
n / p  page
e      export
q      quit

Search exports are saved under:

~/Documents/lex_exports

Verse Web

Verse web mode shows a passage as the visual center, then prints ranked local cross-reference connections with previews:

lex web John 3:16
lex web Romans 1:1 --limit 8

Lexicons, Definitions, And Creeds

Strong's lookup:

lex G3056
lex H7225
lex strongs love

Dictionary and encyclopedia lookup:

lex define covenant
lex define heliodorus

Creeds and confessions:

lex creed
lex creed nicene
lex creed westminster confession

Documentation

• User Guide
• Developer Guide
• Lex CLI Component
• Runtime Data Stores
• Bible DB Builder
• Encyclopedia Importer
• Bible Edition Standard
• Licensing Notes

Data Sources

Lex currently uses local data from:

• ESV-derived Bible database
• Treasury of Scripture Knowledge / OpenBible-style cross-references
• Strong's Hebrew/Greek lexicon data
• STEPBible Greek/Hebrew lexicons
• UBS open-license resources
• Easton's Bible Dictionary
• International Standard Bible Encyclopedia OCR import
• TheologAI historical documents
• Bible geocoding data

The encyclopedia import is incomplete: the current local ISBE import only covers Volume II, Clement-Heresh.

License And Data Terms

Lex application code is intended to be MIT licensed. Bundled and generated data remains under each upstream source's own license or terms.

Do not represent generated databases or third-party datasets as MIT licensed. See Licensing Notes.

Developer Checks

python3 -m py_compile ./lex.py
python3 ./lex.py
python3 ./lex.py --credits
python3 ./lex.py study James 1:1
python3 ./lex.py search covenant -major --limit 2
python3 ./lex.py 2 jn 1:2

Project Status

Lex is usable as a local CLI today. Packaging is still intentionally simple: the tracked entrypoint is lex.py, and the current repo includes generated local databases needed by that script. A proper Python package/release workflow is a good next milestone.