Lex CLI Docs

What's New In 2.6.5

• Geneva 1599 text. The Geneva Bible (gen) is now the 1599 text. Releases up to 2.6.4 shipped an older 1587/KJV-like Geneva database. lex -B gen Genesis 1:1 now reads "In the beginning God created the heauen and the earth."
• Reference parsing. Typographic dashes (John 3:16–18), spaced ranges (John 3:16 - 18) and hyphenated book names (1-chronicles, song-of-solomon) work again.
• npm launcher. When the launcher finds a newer GitHub release than its own version, it now installs that release instead of failing.
• Security hardening. Safer text parsers, safe XML import, restricted update downloads and export paths, and Pillow 13 or newer.
• Dependencies. requirements.txt now matches pyproject.toml, so the npm launcher no longer reinstalls Python packages on every start.

Install And Update

Lex needs Python 3.12 or newer. 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, installs the Python dependencies, and writes a lex wrapper into ~/.local/bin. That wrapper runs the checkout's lex.py directly.

npm Launcher

For a one-line install, use the npm launcher (Node.js 18 or newer):

npm install -g @n8te_/lex-cli
lex --version

The npm package is a small launcher. On first run it downloads the latest Lex GitHub release, verifies its SHA-256 checksum, creates an isolated Python environment, installs the Python dependencies, and caches the full offline app under your user profile. Later runs reuse that cached install.

lex --npm-version   # Node launcher version
lex --version       # Lex application version

Release Archive

To install from a GitHub release archive instead of git clone, check the archive against its checksum file before unpacking:

curl -LO https://github.com/elcafe7/lex/releases/download/v2.6.5/lex-v2.6.5.tar.gz
curl -LO https://github.com/elcafe7/lex/releases/download/v2.6.5/lex-v2.6.5.tar.gz.sha256
shasum -a 256 -c lex-v2.6.5.tar.gz.sha256

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.

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

lex Romans 8
lex read John 1
lex Gen 1

lex Romans 8:28-39
lex John 3:16–18
lex John 3:16 - 18

lex jn3:16
lex 1-chronicles 16:34
lex song-of-solomon 2:1

lex John 3:16, Romans 5:8
lex study John 1:1, John 1:14

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

Command Reference

This section covers the Lex 2.6.5 command surface. Optional flags can usually appear before or after the reference. Most commands show their own help when run without an argument, for example lex search or lex strongs.

Start, Help, Credits

Read Scripture

History

Study

Search

Search looks at verse text only, and likely misspellings are corrected and shown in the result footer. A bare book name in the query is searched as text, so use a scope such as -john to search within a book.

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

Topics, Lexicons, Dictionary

Commentary And Creeds

Export

Manuscript Map

Map a verse to the manuscript readings and witnesses Lex knows about, or open a manuscript profile by name or Gregory-Aland number.

Lex uses bundled or cached manuscript data first. Missing pieces are fetched one at a time from Lex Web and cached under ~/.cache/lex/manuscripts/ for offline reuse.

Interactive Actions

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.

Bible Versions

Lex ships seven Bible editions. The default is the ESV.

Themes

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

Troubleshooting

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.

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.

manifest.json lists every runtime data file with its SHA-256 hash. lex update uses it to download only changed files, and the README has a short script to verify a Git checkout against it.

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.

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 history --limit 5
python3 ./lex.py -B gen Genesis 1:1
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 strongs G3056 --limit 2
python3 ./lex.py define heliodorus

Before changing install behavior, verify the local wrapper target:

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