Local-first Bible study CLI

Lex CLI Docs

Lex reads Scripture, searches local Bible databases, opens interlinear study views, maps cross-references, browses creeds, and exports study work from the terminal.

Version 2.5 Offline SQLite/JSON runtime data macOS/Linux terminal workflow

Install And Update

The recommended install is a full Git checkout because Lex depends on a large local runtime data bundle.

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

setup.sh creates a repo-local virtual environment and writes a lex wrapper into ~/.local/bin. That wrapper runs the checkout's lex.py directly.

Update Code

git pull
./setup.sh

Update Runtime Data

lex update

lex update is data-only. It syncs manifest-tracked files under runtime-data/ and does not overwrite CLI code.

Reference Syntax

References are intentionally forgiving. Full names, common abbreviations, compact references, and chapter-only references are accepted.

Single verse

lex John 3:16
lex jn 3:16
lex 2 jn 1:2

Chapter

lex Romans 8
lex read John 1
lex Gen 1

Verse range

lex Romans 8:28-39
lex export "Romans 8:28-39" --mode read --format pptx

One-time Bible selection

lex -B kjv John 3:16
lex -B lxx Genesis 1:1
lex -B vulg John 1:1

Command Reference

This section is exhaustive for the current local command surface. Optional flags can usually appear before or after the reference.

Start, Help, Credits

Command	Purpose
`lex`	Open the main landing screen.
`lex --version`	Print the plain application version for scripts.
`lex --credits`	Show data credits and source acknowledgements.
`lex update` or `lex --update`	Refresh manifest-managed runtime data.

Read Scripture

Command	Purpose
`lex John 3:16`	Read a verse with nearby context.
`lex read John 3:16`	Explicit read command for a verse.
`lex Romans 8`	Read a full chapter.
`lex --next`	Move to the next verse or chapter from the saved history position.
`lex --prev`	Move to the previous verse or chapter from the saved history position.

History

Command	Purpose
`lex history`	Show recent Lex commands from the local query history.
`lex history --limit 10`	Show a smaller number of recent commands.
`lex history --clear`	Clear the local query history.
`lex history clear`	Alternate clear form.

Study

Command	Purpose
`lex study John 1:1`	Show selected-version context, then source-language study tables, lexicon notes, topical associations, and TSK cross-references.
`lex John 3:16 -i`	Quick study mode using the interlinear flag.
`lex study Romans 1:1 --no-animate`	Disable pauses between study sections.
`lex study Romans 1:1 --animate`	Force pauses between study sections.
`lex -B lxx Genesis 1:1 -i`	Explicit LXX study path. This mode is in progress.
`lex -B vulg John 1:1 -i`	Explicit Vulgate study path. This mode is in progress.

English-version Old Testament study is Masoretic-oriented through the local ESV Hebrew/Aramaic interlinear packet. LXX and Vulgate study data should not auto-populate while studying an English Bible.

Search

Command	Purpose
`lex search israel`	Search Scripture for a word.
`lex search "kingdom of god"`	Search for a phrase, with all-terms fallback.
`lex search israel --page 2`	Open a specific result page.
`lex search israel --limit 25`	Change result count per page.
`lex search covenant -jeremiah`	Scope search to one book.
`lex search beast -daniel-revelation`	Scope search to a book range.
`lex search resurrection -nt`	Scope search to a canon group.

Supported group scopes include -ot, -old-testament, -nt, -new-testament, -law, -pentateuch, -torah, -history, -wisdom, -poetry, -major, -major-prophets, -minor, -minor-prophets, -prophets, -gospels, -epistles, -letters, -pauline, and -general-epistles.

Verse Web

Command	Purpose
`lex web John 3:16`	Show the verse plus ranked local cross-reference connections.
`lex web Romans 1:1 --limit 8`	Control the number of cross-reference rows.

Topics, Lexicons, Dictionary

Command	Purpose
`lex naves grace`	Open a Nave's Topical Bible entry.
`lex topic grace`	Alias for Nave's topic lookup.
`lex naves John 3:16`	Find topical associations for a verse.
`lex G3056`	Look up a Strong's Greek number.
`lex H7225`	Look up a Strong's Hebrew number.
`lex strongs love`	Search Strong's entries by English gloss.
`lex define covenant`	Show local dictionary and encyclopedia entries.

Commentary And Creeds

Command	Purpose
`lex commentary John 3:16`	Show local commentary notes for a verse.
`lex commentary Romans 1`	Show local commentary notes for a chapter.
`lex creed`	Open the creed and confession navigator.
`lex creed nicene`	Open a specific creed or confession by search term.
`lex creed westminster confession`	Open a longer historical document by name.

Export

Command	Purpose
`lex export "John 3:16"`	Open an interactive export menu.
`lex export "Romans 8:28-39" --mode read --format pptx`	Export read-mode verses to PPTX.
`lex export "Romans 8:28-39" --mode read --format png`	Export read-mode verses to PNG images.
`lex export "John 1:1" --mode study --format pdf`	Export study packet as PDF.
`lex export "John 1:1" --mode study --format docx`	Export study packet as DOCX.
`lex export "John 3:16" --mode web --format pdf`	Export verse web data as PDF.
`lex export "John 3:16" --mode web --format docx`	Export verse web data as DOCX.

Interactive Actions

Mode	Keys
Study	`n` next verse, `p` previous verse, `r` read context, `w` verse web, `e` export, `q` done.
Search	`1-10` study result, `r #` read result, `n`/`p` page, `e` export, `q` quit.
Creeds	`n` next section, `p` previous section, `m` menu, `q` quit.
Read	Verse and chapter reads expose export actions in interactive terminals.

Exports

Lex writes exports under ~/Documents/lex_exports. Study packets go under ~/Documents/lex_exports/studies. The app tries to open finished files automatically and prints the path if the desktop blocks that.

Mode	Formats	Notes
Read	PNG, PPTX	Use `--ratio 16:9` or `--ratio 1:1` for PNG exports.
Study	DOCX, PDF	Interactive study export also offers a PPTX verse slide.
Search	DOCX, PDF, PPTX	Exports the current result page from interactive search.
Verse Web	DOCX, PDF	Exports verse plus cross-reference connection data.

Bible Versions

Lex supports ESV, KJV, KJ16, NASB, Geneva, LXX, and Vulgate runtime databases when present locally.

Command	Purpose
`lex -v`	Open the interactive Bible version picker.
`lex version kjv`	Persistently set the default Bible version.
`lex -v nasb`	Persistently set the default Bible version by short flag.
`lex -B lxx Genesis 1:1`	Use a Bible version for one command only.

Themes

Lex chooses a theme from explicit flags, environment variables, saved config, terminal hints, and platform appearance.

Command	Purpose
`lex -light`	Persist Studio Light theme.
`lex -dark`	Persist Blueprint Technical theme.
`lex -auto`	Clear saved theme and return to automatic detection.
`LEX_THEME=dark lex John 3:16`	Override the theme for one command.
`LEX_NO_COLOR=1 lex John 3:16`	Disable Lex color intentionally.

Troubleshooting

Symptom	What To Check
`lex` not found	Confirm `~/.local/bin` is on `PATH` and rerun `./setup.sh`.
Wrong checkout running	Run `type -a lex` and `head -5 ~/.local/bin/lex`.
No reference result	Try the full book name, such as `lex 1 Corinthians 13`.
No study data	The verse can still be read, but study requires the matching local source-language dataset.
Missing encyclopedia entry	The local ISBE import is incomplete and currently covers only part of the source material.

Developer Backend Overview

lex.py is the active tracked CLI. It owns argument parsing, local SQLite access, JSON loading, terminal rendering, update checks, export generation, and interactive action loops.

Entry Point

main() parses CLI flags and dispatches to LexAgent methods.

Database Wrapper

LexDB is a small SQLite query helper used by read, search, study, creeds, and dictionaries.

Runtime Agent

LexAgent resolves references, opens data stores, lazily loads JSON, renders output, and handles exports.

State

Last navigation position is stored in ~/.lex_history. Recent command history is stored in ~/.lex_query_history. Theme config is stored in ~/.lex_config.json.

Runtime Data

A normal checkout resolves data under runtime-data/. If the runtime bundle is absent, Lex can fall back to ~/bible-lexicon-data for local developer worktrees.

Path	Use
`runtime-data/lexicon.db`	Legacy combined data and update sentinel.
`runtime-data/bible_versions/*.db`	Per-edition Bible text for read and search.
`runtime-data/esv-data/data/esv/esv-interlinear.json`	ESV-backed Hebrew/Greek interlinear rows.
`runtime-data/esv-data/data/interlinear/strongs.json`	Interlinear Strong's metadata.
`runtime-data/lxx.db`	In-progress LXX morphology study data.
`runtime-data/cross_refs.db`	Treasury of Scripture Knowledge cross-reference graph.
`runtime-data/strongs.db`	Strong's lookup data.
`runtime-data/dictionary.db`	Dictionary entries.
`runtime-data/encyclopedia.db`	ISBE encyclopedia entries.
`runtime-data/creeds.db`	Creed/confession index rows.
`runtime-data/theolog-ai/data/historical-documents`	JSON fallback for full creed/confession texts.

Study Boundaries

Study mode has an important source-tradition boundary.

Render the selected Bible version as the context panel first.
English Old Testament study remains Masoretic-oriented through ESV Hebrew/Aramaic interlinear data.
LXX study is a separate, in-progress path selected explicitly with -B lxx.
Vulgate study is a separate, in-progress path selected explicitly with -B vulg.
Do not populate LXX or Vulgate study rows while the selected Bible is English.
Do not fall back across source traditions by matching only book/chapter/verse suffixes.

CLI Dispatch

main() keeps command routing thin. Feature behavior should live on LexAgent methods.

Route	Backend Method
`read` or bare reference	`display_verse()` / `render_chapter()`
`study` or `-i`	`display_verse(..., interlinear=True)` then `display_study()`
`web`	`display_verse_web()`
`search`	`display_search()`
`naves` / `topic`	`display_naves()`
`strongs` / `G####` / `H####`	`display_strongs()` or English Strong's search
`define`	Dictionary plus encyclopedia lookup
`creed`	`display_creed_navigator()`
`export`	`prompt_bulk_export()` or `handle_bulk_export()`

Verification

Minimum local checks after CLI changes:

python3 -m py_compile ./lex.py
python3 ./lex.py --version
python3 ./lex.py read John 3:16
python3 ./lex.py study Genesis 1:1 --no-animate
python3 ./lex.py -B lxx Genesis 1:1 -i --no-animate
python3 ./lex.py search israel --limit 2
python3 ./lex.py define heliodorus

Before changing install behavior, verify the local wrapper target:

type -a lex
head -5 ~/.local/bin/lex