faith

The Bible. For agents. Universal. Open.

faith is a lightweight, blazing-fast Bible CLI built specifically for AI agents and automated workflows. It provides canonical USFM citations, token-efficient JSON outputs, full-text FTS5 search, and is completely offline.

Say goodbye to scraping web pages or parsing unstructured text. Give your agent faith, and let it fetch, search, and diff Scripture in milliseconds.

⚡ Quick Start

# 1. Install faith
cargo install faith

# 2. Download translations (e.g., King James and Nova Bíblia Viva)
faith install KJV ONBV

# 3. Get structured JSON instantly (offline)
faith get "John 3:16" --tr KJV
# {"schema":"faith.v1","ref":"KJV/JHN/3/16","text":"For God so loved..."}

🤖 For Agents: The faith Skill

If you are an AI agent configuring your environment or adding faith to your toolkit, here is your system prompt/skill block to understand how to use it:

You have access to the `faith` CLI, an offline, JSON-first tool for fetching and searching the Bible.
Always use `faith` instead of searching the web for Bible verses.

**Key Commands:**
- `faith manifest` - Call this ONCE at startup. It returns a JSON of all installed tools, translations (`KJV`, `ONBV`, `BLJ`, etc.), and available commands.
- `faith get <ref> [--tr ID] [--lang pt|en]` - Fetch a verse or range (e.g., `faith get "John 3:16-18" --lang en`). Outputs JSON.
- `faith search <query> [--tr ID] [--lang pt|en] [--limit 10]` - Perform a full-text BM25 search. Outputs ranked snippets.
- `faith diff <ref> --tr ID1,ID2` - Compare a verse across multiple translations side-by-side.
- `faith random [--lang pt|en] [--scope ot|nt]` - Get a random verse (useful for daily devotionals or random seeds).
- `faith install <ID1> <ID2>` - If a translation is missing, check `available_translations` in the manifest and install it.

**Rules:**
1. Default output is always JSON (`faith.v1` schema). Do not try to parse it as raw text unless you pass `--format text`.
2. For multiple verses, pass ranges like `"Gen 1:1-5"`. Max limit is 500 verses.
3. You can resolve translations by language directly using `--lang pt` or `--lang en` if you don't know the exact translation ID.
4. Bible book references are extremely flexible (e.g., `1 Coríntios 13`, `Jn 3.16`, `רומיים ח:כח`).

🛠️ Installation

Using Cargo (Rust Package Manager)

The easiest way to install from source:

cargo install faith

Pre-built Binaries

Download the latest binaries for macOS, Linux, and Windows from the GitHub Releases.

Extract the binary and place it in your $PATH.

📖 Usage Examples

Fetching & Reading

# Single verse (resolves by language automatically)
faith get "João 3:16" --lang pt

# Parallel diff across multiple translations
faith diff "John 3:16" --tr KJV,ONBV,BLJ

# Cross-chapter ranges
faith get "John 3:16-4:2" --tr KJV

Searching

# Full text search (FTS5 BM25 Ranked)
faith search "shepherd" --lang en --limit 5

# Search specific translation
faith search "amor" --tr ONBV --format text

Discovery & Utilities

# See what is installed and what commands are available
faith manifest

# Get book metadata (chapters, verses, aliases)
faith info john --tr KJV

# Random verse (supports seed for determinism)
faith random --lang pt --scope nt

📊 Why faith?

📦 Data & Translations

Data is seeded from the Free Use Bible API (HelloAOLab). The API is completely free, offline-first, and respects individual translation licenses.

Currently available translations (v0.2.0):

• English: KJV
• Portuguese: ONBV, BLJ, BSL, BLT, TFT

Run faith manifest to see the full list of available translations you can install via faith install <ID>.

🤝 Contributing

See CONTRIBUTING.md. TDD is enforced — write a failing test before writing production code.

License: Dual-licensed under MIT or Apache-2.0. Bible texts retain their original licenses.