<div align="center">
<img src="assets/logo.svg" alt="faith" width="180" />
# faith
**The Bible. For agents. Universal. Open.**
[](https://crates.io/crates/faith)
[](https://crates.io/crates/faith)
[](https://docs.rs/faith)
[](https://www.rust-lang.org)
[](#license)
</div>
`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
```bash
# 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:
<details>
<summary><b>Click to expand Agent Skill Prompt</b></summary>
```markdown
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`, `ืจืืืืื ื:ืื`).
```
</details>
---
## ๐ ๏ธ Installation
### Using Cargo (Rust Package Manager)
The easiest way to install from source:
```bash
cargo install faith
```
### Pre-built Binaries
Download the latest binaries for macOS, Linux, and Windows from the [GitHub Releases](https://github.com/V-Gutierrez/faith/releases).
Extract the binary and place it in your `$PATH`.
---
## ๐ Usage Examples
### Fetching & Reading
```bash
# 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
```bash
# 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
```bash
# 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`?
| Primary audience | **Agents / Scripts** | Humans (TUI) |
| JSON output (default) | โ
| โ |
| Full-text FTS5 Search | โ
| varies |
| Canonical USFM refs (`JHN/3/16`) | โ
| โ |
| Multi-translation in one call | โ
| โ |
| Multi-locale ref parser | โ
| โ |
| Cold start | **~50 ms** (Rust) | Slower (Node/Python) |
---
## ๐ฆ Data & Translations
Data is seeded from the [Free Use Bible API](https://bible.helloao.org) (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`](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.