Bible Terminal

An offline-first command-line application for reading and searching the Bible without leaving the terminal.

Status

The Go CLI is under active development and includes an offline WEBP reader backed by an embedded SQLite database. Reading output is styled when used in a terminal and automatically switches to stable plain text when redirected. See docs/PLAN.md for the product scope, architecture, milestones, and acceptance criteria.

Product direction

The initial interface will be command-oriented and friendly to both people and shell pipelines:

bible read John 3
bible read "John 3:16"
bible read "John 3:16-21" --plain
bible search "for God so loved"
bible books
bible random

The currently implemented commands include:

bible read John 3
bible read "John 3:16"
bible read "John 3:16-21"
bible read Jn 3:16 --plain
bible read John 3 --next
bible read Matthew 1 --previous
bible read "1 Cor 13"
bible books
bible search "living water"
bible random
bible translations
bible config show

bible books lists all canonical names, source codes, and accepted aliases. Chapter navigation crosses book boundaries, so moving forward from John 21 reads Acts 1 and moving backward from Matthew 1 reads Malachi 4.

Output adapts to its destination:

bible read "Psalm 23"          # styled terminal output
bible read "Psalm 23" --plain  # stable tab-separated output
bible read "Psalm 23" | less   # automatically plain, with no ANSI escapes
bible read "Psalm 23" --no-color # readable layout without terminal colors

--plain and --no-color are global flags and may appear before or after the subcommand.

Search works entirely offline and returns verses containing every query token, ranked by relevance with canonical Scripture order as a stable tie-breaker. Matching words are emphasized in interactive colored output:

bible search "living water"
bible search "faith hope love" --limit 10
bible search "kingdom of God" --plain

The default result limit is 20. Use --limit (or -n) to request between 1 and 100 results. Punctuation and case do not affect matching. A plain search with no matches writes no output, making it safe to use in shell pipelines. Match highlighting never changes --no-color, --plain, or redirected verse text.

Discovery commands also work offline:

bible random
bible random --plain
bible translations

bible random selects uniformly from all 31,103 bundled WEBP verses. bible translations reports the bundled text edition, language, canon, source, public-domain rights notice, trademark notice, and publisher text policy.

Configuration

Bible Terminal uses the same configuration convention on macOS and Linux. The path is resolved in this order:

1. $BIBLE_TERMINAL_CONFIG_HOME/config.json
2. $XDG_CONFIG_HOME/bible-terminal/config.json
3. ~/.config/bible-terminal/config.json

The first two environment variables must contain absolute paths. Inspect and change preferences with the CLI instead of editing JSON directly:

bible config path
bible config show
bible config set plain true
bible config set color false
bible config set translation webp
bible config reset

Saved preferences provide defaults. Explicit command-line flags take priority, including --plain=false and --no-color=false. Redirected output remains plain even when the saved plain preference is false.

The first release should:

• work completely offline;
• start quickly and ship as a single executable;
• understand common Bible reference formats and book aliases;
• produce readable terminal output and clean redirected output;
• use Bible text that is legally redistributable; and
• leave room for additional languages and translations.

Proposed stack

• Go
• Cobra for CLI command parsing
• SQLite with full-text search
• Lip Gloss for terminal presentation
• Bubble Tea later, if a full-screen reader proves useful

Development

The project requires Go 1.26 or newer and Make. Run the complete local check:

make check
./bin/bible version

See CONTRIBUTING.md for the development workflow and Bible text licensing requirements.

Installation

Tagged releases ship checksummed single-binary archives for macOS and Linux on Intel/AMD64 and ARM64. Public release downloads require no GitHub account, API token, or GitHub CLI. See the installation guide for archive verification, installation, source builds, and Bash, Zsh, Fish, and PowerShell completion setup.

License

Bible Terminal's source code is licensed under the MIT License. Bible translations are separate works with their own copyright and redistribution terms; no translation should be bundled until its license and required attribution have been verified and documented. See Third-Party Notices for the bundled World English Bible text's provenance, public-domain status, trademark notice, and text policy.