# biblestudy-cli
[](https://github.com/labrack/biblestudy-cli/releases)
[](https://github.com/labrack/biblestudy-cli/commits/main)
[](https://www.python.org/)
[](https://github.com/labrack/biblestudy-cli/blob/main/LICENSE)
[](https://openai.com/)
[](https://docs.api.bible/)
[](https://api.nlt.to/)
[](https://api.esv.org/)
BibleStudy CLI — a text-based Bible study companion for your terminal.
Powered by [api.bible](https://docs.api.bible/), [api.nlt.to](https://api.nlt.to), [api.esv.org](https://api.esv.org), and OpenAI.
Inspired by [SimplyScripture](https://mysimplyscripture.com/).
> **Note:** Neither I nor this tool are affiliated with SimplyScripture — I just like their concept and wanted a CLI version.
---
## ✨ Features
- Input or detect Bible references (e.g., `John 3:16`)
- Choose from the following translations:
- ✅ NLT (New Living Translation) — via `api.nlt.to`
- ✅ ESV (English Standard Version) — via `api.esv.org`
- ✅ FBV (Free Bible Version)
- ✅ KJV (King James Version)
- ✅ ASV (American Standard Version)
- ✅ WEB (World English Bible)
- Retrieve verse content and:
- ✏️ Simplify it
- 🗣️ Translate into modern speech
- 🏺 Reveal historical background
- 🔗 Cross-reference other scriptures
- 🔍 Highlight key terms
- 🛠️ Apply to daily life
- 📅 Verse of the Day support (automatically shown on launch or via Option 9)
- Save study notes automatically
- Works in any terminal — beautiful output powered by `rich`
---
## 🚀 Quickstart
## 🔐 API Keys Setup
You'll need:
- **OpenAI API key** ([Get one here](https://platform.openai.com/account/api-keys))
- **api.bible key** ([Sign up here](https://docs.api.bible/))
- **NLT API key** ([Request access here](https://api.nlt.to/))
- **ESV API key** ([Request access here](https://api.esv.org))
Set environment variables:
```bash
export OPENAI_API_KEY=your-openai-key
export BIBLE_API_KEY=your-api-bible-key
export NLT_API_KEY=your-nlt-api-key
export ESV_API_KEY=your-esv-api-key
export BIBLESTUDY_NOTES_DIRECTORY=./notes # optional override
```
Or use `config.py` locally (not recommended for production).
### Install from PyPI
This package is published to PyPI, so you can install using pip directly:
```bash
pip install biblestudy
biblestudy
```
### ...OR Install Locally
To install the package locally for development or testing:
```bash
# Clone the repository (if you haven't already)
git clone https://github.com/labrack/biblestudy-cli.git
cd biblestudy-cli
# Install the package in development mode
pip install .
```
This is equivalent to the old way of running `python main.py`, but now the `biblestudy` command is available system-wide after installation.
---
## 🚀 Requirements
- Python 3.9+
- `requests`, `openai`, `rich`, `beautifulsoup4`
Install dependencies:
```bash
pip install -r requirements.txt
```
---
## ▶️ Running the App
Once installed, you can run the Bible study CLI from anywhere:
```bash
# Run the CLI using the installed command
biblestudy
```
---
## 💬 Sample Run
```bash
📖 Welcome to the Bible Study CLI 📖
Enter a Bible reference (e.g., John 3:16) or a snippet of scripture.
>> John 3:16
Which translation would you like to use?
[1] NLT (New Living Translation)
[2] ESV (English Standard Version)
[3] FBV (Free Bible Version)
[4] KJV (King James Version)
[5] ASV (American Standard Version)
[6] WEB (World English Bible)
Enter the number for your translation [1-6]: 1
Fetching NLT passage: John 3:16... done.
📜 John 3:16
╭────────────────────────────────────────────────────────────────────────────╮
│ For God loved the world so much that he gave his one and only Son, so │
│ that everyone who believes in him will not perish but have eternal life. │
╰────────────────────────────────────────────────────────────────────────────╯
What would you like to do?
[1] ✏️ Simplify
[2] 🗣️ Modern English
[3] 🏺 Background
[4] 🔗 Cross-References
[5] 🔍 Keyword Focus
[6] 🛠️ Life Application
[7] 🔄 Change Translation for Current Reference
[8] ➕ Enter a New Bible Reference
[9] 📅 Show the Verse of the Day
[0] 🚪 Exit
```
---
## 💾 Saving Notes
Your study results are saved to the `notes/` folder by default.
You can change the location with the `BIBLESTUDY_NOTES_DIRECTORY` environment variable.
---
## 💡 Tips for Development
- Don't commit your real API keys — use the provided `.gitignore` to ignore `config.py`
- Use `.env.example` as a template for local testing
- Notes are plain `.txt` files and easy to back up
---
## 🍎 Mac-Specific Notes
If you see a warning like this:
```
NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently using LibreSSL
```
✅ You can safely ignore it, or pin `urllib3<2` in your requirements to avoid it.
---
## 🔮 Future Ideas
- Add fuzzy search for snippets (e.g. "love is patient")
- Support full chapter navigation
- Offline caching for entire books
- Save notes in Markdown format
- Session resume after crash
- UI upgrade using `textual` or `urwid`
---
## 📜 License
MIT License — use freely and contribute back!
Raw data
{
"_id": null,
"home_page": null,
"name": "biblestudy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "bible, study, cli, terminal, scripture, devotional",
"author": null,
"author_email": "labrack <labrack@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/a1/48/100bef92e40ed3036e50b3afabf3884f4ace290cda31821f633117e26f5c/biblestudy-1.4.2.tar.gz",
"platform": null,
"description": "# biblestudy-cli\n\n[](https://github.com/labrack/biblestudy-cli/releases)\n[](https://github.com/labrack/biblestudy-cli/commits/main)\n[](https://www.python.org/)\n[](https://github.com/labrack/biblestudy-cli/blob/main/LICENSE)\n\n[](https://openai.com/)\n[](https://docs.api.bible/)\n[](https://api.nlt.to/)\n[](https://api.esv.org/)\n\nBibleStudy CLI \u2014 a text-based Bible study companion for your terminal.\n\nPowered by [api.bible](https://docs.api.bible/), [api.nlt.to](https://api.nlt.to), [api.esv.org](https://api.esv.org), and OpenAI. \nInspired by [SimplyScripture](https://mysimplyscripture.com/).\n\n> **Note:** Neither I nor this tool are affiliated with SimplyScripture \u2014 I just like their concept and wanted a CLI version.\n\n---\n\n## \u2728 Features\n\n- Input or detect Bible references (e.g., `John 3:16`)\n- Choose from the following translations:\n - \u2705 NLT (New Living Translation) \u2014 via `api.nlt.to`\n - \u2705 ESV (English Standard Version) \u2014 via `api.esv.org`\n - \u2705 FBV (Free Bible Version)\n - \u2705 KJV (King James Version)\n - \u2705 ASV (American Standard Version)\n - \u2705 WEB (World English Bible)\n- Retrieve verse content and:\n - \u270f\ufe0f Simplify it\n - \ud83d\udde3\ufe0f Translate into modern speech\n - \ud83c\udffa Reveal historical background\n - \ud83d\udd17 Cross-reference other scriptures\n - \ud83d\udd0d Highlight key terms\n - \ud83d\udee0\ufe0f Apply to daily life\n- \ud83d\udcc5 Verse of the Day support (automatically shown on launch or via Option 9)\n- Save study notes automatically\n- Works in any terminal \u2014 beautiful output powered by `rich`\n\n---\n\n## \ud83d\ude80 Quickstart\n\n## \ud83d\udd10 API Keys Setup\n\nYou'll need:\n\n- **OpenAI API key** ([Get one here](https://platform.openai.com/account/api-keys))\n- **api.bible key** ([Sign up here](https://docs.api.bible/))\n- **NLT API key** ([Request access here](https://api.nlt.to/))\n- **ESV API key** ([Request access here](https://api.esv.org))\n\nSet environment variables:\n\n```bash\nexport OPENAI_API_KEY=your-openai-key\nexport BIBLE_API_KEY=your-api-bible-key\nexport NLT_API_KEY=your-nlt-api-key\nexport ESV_API_KEY=your-esv-api-key\nexport BIBLESTUDY_NOTES_DIRECTORY=./notes # optional override\n```\n\nOr use `config.py` locally (not recommended for production).\n\n\n### Install from PyPI\n\nThis package is published to PyPI, so you can install using pip directly:\n\n```bash\npip install biblestudy\nbiblestudy\n```\n### ...OR Install Locally\n\nTo install the package locally for development or testing:\n\n```bash\n# Clone the repository (if you haven't already)\ngit clone https://github.com/labrack/biblestudy-cli.git\ncd biblestudy-cli\n\n# Install the package in development mode\npip install .\n```\nThis is equivalent to the old way of running `python main.py`, but now the `biblestudy` command is available system-wide after installation.\n\n---\n\n## \ud83d\ude80 Requirements\n\n- Python 3.9+\n- `requests`, `openai`, `rich`, `beautifulsoup4`\n\nInstall dependencies:\n\n```bash\npip install -r requirements.txt\n```\n\n---\n\n## \u25b6\ufe0f Running the App\n\nOnce installed, you can run the Bible study CLI from anywhere:\n\n```bash\n# Run the CLI using the installed command\nbiblestudy\n```\n\n---\n\n## \ud83d\udcac Sample Run\n\n```bash\n\ud83d\udcd6 Welcome to the Bible Study CLI \ud83d\udcd6\n\nEnter a Bible reference (e.g., John 3:16) or a snippet of scripture.\n\n>> John 3:16\n\nWhich translation would you like to use?\n[1] NLT (New Living Translation)\n[2] ESV (English Standard Version)\n[3] FBV (Free Bible Version)\n[4] KJV (King James Version)\n[5] ASV (American Standard Version)\n[6] WEB (World English Bible)\n\nEnter the number for your translation [1-6]: 1\n\nFetching NLT passage: John 3:16... done.\n\n\ud83d\udcdc John 3:16\n\u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 For God loved the world so much that he gave his one and only Son, so \u2502\n\u2502 that everyone who believes in him will not perish but have eternal life. \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n\nWhat would you like to do?\n[1] \u270f\ufe0f Simplify\n[2] \ud83d\udde3\ufe0f Modern English\n[3] \ud83c\udffa Background\n[4] \ud83d\udd17 Cross-References\n[5] \ud83d\udd0d Keyword Focus\n[6] \ud83d\udee0\ufe0f Life Application\n[7] \ud83d\udd04 Change Translation for Current Reference\n[8] \u2795 Enter a New Bible Reference\n[9] \ud83d\udcc5 Show the Verse of the Day\n[0] \ud83d\udeaa Exit\n```\n\n---\n\n## \ud83d\udcbe Saving Notes\n\nYour study results are saved to the `notes/` folder by default. \nYou can change the location with the `BIBLESTUDY_NOTES_DIRECTORY` environment variable.\n\n---\n\n## \ud83d\udca1 Tips for Development\n\n- Don't commit your real API keys \u2014 use the provided `.gitignore` to ignore `config.py`\n- Use `.env.example` as a template for local testing\n- Notes are plain `.txt` files and easy to back up\n\n---\n\n## \ud83c\udf4e Mac-Specific Notes\n\nIf you see a warning like this:\n\n```\nNotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently using LibreSSL\n```\n\n\u2705 You can safely ignore it, or pin `urllib3<2` in your requirements to avoid it.\n\n---\n\n## \ud83d\udd2e Future Ideas\n\n- Add fuzzy search for snippets (e.g. \"love is patient\")\n- Support full chapter navigation\n- Offline caching for entire books\n- Save notes in Markdown format\n- Session resume after crash\n- UI upgrade using `textual` or `urwid`\n\n---\n\n## \ud83d\udcdc License\n\nMIT License \u2014 use freely and contribute back!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A text-based Bible study companion for your terminal",
"version": "1.4.2",
"project_urls": {
"Homepage": "https://github.com/labrack/biblestudy-cli",
"Issues": "https://github.com/labrack/biblestudy-cli/issues",
"Repository": "https://github.com/labrack/biblestudy-cli"
},
"split_keywords": [
"bible",
" study",
" cli",
" terminal",
" scripture",
" devotional"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0efb1e41e10ab9cd789ae21a7cfb528791296964b203dc524d8528d1f23726c1",
"md5": "772611f18d9c1753ec0d491d69d6a077",
"sha256": "bbf5d29ad46b28de1d1e9a28fcf3c12893cfceec2d9be7098b3266b729cc724a"
},
"downloads": -1,
"filename": "biblestudy-1.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "772611f18d9c1753ec0d491d69d6a077",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 17149,
"upload_time": "2025-07-14T17:59:27",
"upload_time_iso_8601": "2025-07-14T17:59:27.526485Z",
"url": "https://files.pythonhosted.org/packages/0e/fb/1e41e10ab9cd789ae21a7cfb528791296964b203dc524d8528d1f23726c1/biblestudy-1.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a148100bef92e40ed3036e50b3afabf3884f4ace290cda31821f633117e26f5c",
"md5": "e54b5c96974998deefd893e048357c5d",
"sha256": "f3e2598620fcd5c99420d57ae4ca49cfcc843f222ca15e01c22ce858153d7b22"
},
"downloads": -1,
"filename": "biblestudy-1.4.2.tar.gz",
"has_sig": false,
"md5_digest": "e54b5c96974998deefd893e048357c5d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 18176,
"upload_time": "2025-07-14T17:59:28",
"upload_time_iso_8601": "2025-07-14T17:59:28.674821Z",
"url": "https://files.pythonhosted.org/packages/a1/48/100bef92e40ed3036e50b3afabf3884f4ace290cda31821f633117e26f5c/biblestudy-1.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 17:59:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "labrack",
"github_project": "biblestudy-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"<",
"2"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.7.0"
]
]
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.12.0"
]
]
}
],
"lcname": "biblestudy"
}
JSON
