Logos Launcher
Raycast extension with commands that open verses, run searches, and browse resources in Logos Bible Software.
Table of Contents
Commands
Open Verse in Logos
- Accepts input like
nasb John 3:16 (alias + reference) or John 3:16 (reference only).
- Resolves Bible version aliases defined in command preferences.
- Builds a ref.ly deep link and opens it in Logos (optional clipboard copy for debugging).
- Validates empty input and unknown aliases with clear toasts.
Search Library
- Reads the local Logos
catalog.db, indexes titles, authors, abbreviations, and resource IDs.
- Provides a Raycast list with fuzzy search, loading state, and quick actions to open or copy links.
- Caches the parsed catalog to speed up future runs and exposes a Rebuild Index action.
- Falls back gracefully when the database is missing or permissions block access.
- Uses a configurable fuzzy match threshold that defaults to
0.3, so you can rely on sensible results without touching preferences on first run.
Logos All Search
- Opens the Logos All Search UI via
https://ref.ly/logos4/Search with kind=AllSearch and syntax=v2.
- Accepts any text query and launches the search directly in Logos.
Logos Bible Search
- Opens the Logos Bible Search UI via
https://ref.ly/logos4/Search with kind=BibleSearch.
- Quickly toggle between Smart Search (Semantic) and Precise Search (Lexical) in command preferences.
- Smart search matches concepts and synonyms, while Precise search matches exact phrases.
Bible Word Study
- Streams suggestions straight from Logos'
AutoComplete.db, so typing a couple of letters surfaces the same lemmas, transliterations, and English senses you see inside Logos.
- Selecting a row fires Logos'
bws … command with the canonical reference (plus multiple logos4: and ref.ly fallbacks) to reliably launch the Bible Word Study guide.
- Includes quick actions to copy the command, the underlying word sense identifier, or reveal the AutoComplete database when you need to troubleshoot.
Search Factbook
- Queries Logos'
AutoComplete.db on demand so you can type a couple of letters and immediately see matching Factbook topics (people, places, timelines, themes, etc.).
- Returns the official topic label, category icon, and raw Factbook URI so you always know the exact identifier Logos expects.
- Opens the highlighted topic in Factbook or copies the
logos4:Factbook;ref=… URI for reuse.
Exegetical Guide
- Acts as a quick launcher: type a Bible passage (for example
Matthew 5 or James 2:1-13) and hit Return.
- Built-in book parsing converts Bible references into
ref=BibleESV.Mt5… (or whichever prefix you configure), so you always land on the correct passage instead of the last guide state.
- Reference prefix defaults to
BibleESV; switch it to BibleNASB95, BibleLSB, etc. in the command preferences if you want another translation.
- Opens your chosen guide title (default
My Exegetical Guide) through ref.ly/logos4/Guide?t=…&ref=…, with additional logos4: fallbacks plus quick actions to copy either URI.
Reading Plans
- Lists the reading plans stored in each account's
Documents/ReadingPlan/ReadingPlan.db so you can reach today's assignment with a single press of Return.
- Opens the plan's Logos URI directly, which jumps to the assigned passage inside the app.
- Provides a reload action plus a quick way to reveal the underlying
ReadingPlan.db file for troubleshooting.
Open Logos Layout
- Shows your saved layouts (from
LayoutManager/layouts.db) and lets you filter them instantly as you type.
- Launches the selected layout right away through its stored Logos URI.
- Use the built-in action panel to copy the URI, reload the list, or reveal
layouts.db.
Logos Tools Launcher
- Surfaces a curated catalog of Logos tools, builders, and interactives (Atlas, Text Comparison, Study Assistant, Sermon Builder, Copy Bible Verses, Advanced Timeline, Systematic Theologies, Psalms Explorer, etc.) with instant filtering.
- Includes synonyms, command phrases, and interactive IDs so Raycast's autocomplete matches whatever you remember typing in Logos' command box.
- Opening a tool cycles through ref.ly,
logos4: and logos4-command:// URIs to reliably launch the target view, plus quick actions let you copy the command text or URI for reuse.
Configuration
Version Aliases (Open Verse command)
- Default Version is required (for example
esv).
- Version Aliases accepts either JSON (
{"nasb":"nasb95"}) or comma-separated alias=version pairs in the preference field.
- Suggested starters you can copy into the preference:
{
"niv": "niv2011",
"nasb": "nasb95",
"msg": "message",
"esv": "esv",
"lsb": "lsb",
"leb": "leb",
"nlt": "nlt",
"kjv": "kjv",
"nkjv": "nkjv",
"rsv": "rsv"
}
- Prefer plain text? Paste the same list as a single comma-separated line:
niv=niv2011, nasb=nasb95, msg=message, esv=esv, lsb=lsb, leb=leb, nlt=nlt, kjv=kjv, nkjv=nkjv, rsv=rsv
- Unknown aliases surface a toast so you can adjust preferences quickly.
Catalog Database (Search Library command)
- Automatically locates the most recent
catalog.db under ~/Library/Application Support/Logos4/Data/*/LibraryCatalog/.
- Provide a custom path in preferences to override auto-discovery (tilde expansion supported).
- Use the Action Panel to rebuild the index after purchasing resources or to reveal the database in Finder.
Fuzzy Match Threshold (Search Library command)
- Defaults to
0.3, which balances recall and precision for most libraries.
- Leave the preference blank to stick with
0.3, then tweak it later from the command settings when you want stricter (closer to 0) or looser (closer to 1) matches.
- The field is optional, so the command never blocks on first launch just to set a number.
AutoComplete Database (Search Factbook & Bible Word Study commands)
- Auto-detects the latest
AutoComplete.db under ~/Library/Application Support/Logos*/Data/*/AutoComplete/.
- Provide a custom path in each command's preferences if your Logos data lives elsewhere (tilde expansion supported).
- Results are fetched live (type ≥2 characters) so updates in Logos become available instantly after reloading the database.
- Uses macOS' built-in
sqlite3 tool under the hood, so the commands won't run until Command Line Tools are installed.
Documents Database (Reading Plans & Layouts)
- Automatically scans
~/Library/Application Support/Logos*/Documents/*/ (and Verbum variants) for Documents/ReadingPlan/ReadingPlan.db and LayoutManager/layouts.db, then loads the freshest file.
- Override the path in each command's preferences with either the database file itself or any folder that contains it (tilde expansion supported).
- Both commands have reload + reveal actions so you can refresh the list after creating or renaming items in Logos.
Open Schemes
- Verses currently use
ref.ly links for reliability.
- Library resources try
logosres:{id} first and fall back to logos4:Open?resource={id} if needed.
Troubleshooting
- Launch Logos once so the catalog database exists before running the Search Library command.
- If macOS blocks disk access, grant Raycast (or the Raycast Extension development environment) Full Disk Access and rerun indexing.
- When deep links fail to open Logos, copy the URL from the toast/clipboard and test it in a browser to verify the handler.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for:
- Development setup instructions
- Code style guidelines
- Testing requirements
- Pull request process
Quick Start for Contributors
# Clone and install
git clone https://github.com/michael_marvive/logos-search.git
cd logos-search
npm install
# Start development
npm run dev
# Run tests
npm test
# Check code style
npm run lint
Sponsorship
If you find Logos Launcher useful, consider supporting its development:
Your support helps maintain and improve this extension!
Branch Protection
The main branch has the following protections enabled:
- Require pull request reviews before merging
- Require status checks to pass before merging
- Require linear history
- Do not allow force pushes
License
This project is licensed under the MIT License - see the LICENSE file for details.
