BIBLEIT / Documentation

Protocol reference

The version 1 command protocol is shared by SSH and the HTTP command endpoint. Keywords are case-insensitive. Quote arguments containing spaces. Start with HELP to discover commands allowed for your identity.

Connect over SSH

Register your public key in Settings → SSH keys before connecting. Local development uses port 2222; the hosted SSH endpoint uses port 22. An unknown or revoked key is rejected during the handshake.

ssh -p 2222 -i ~/.ssh/bibleit_local_dev -o IdentitiesOnly=yes bibleit-cli@127.0.0.1

HELP
HELP TRANSLATION
HELP LIVE

Responses and streaming

Each command returns one response envelope: OK for success, ERR for failure, or OK followed by records and END for multiple records. EVENT messages are unsolicited subscription updates. Match command replies in FIFO order; protocol v1 has no request IDs. Events can arrive between response envelopes, never inside them.

String values are quoted and escape quotes and backslashes. Booleans are true/false and counts are integers. translation identifies the edition; book, chapter, and verse locate the passage; text is Scripture text. verses/results/count describe the number of following records. Accept additional response fields for forward compatibility.

ERR forbidden
ERR rate_limited retry_after_ms=250
EVENT clear

Examples use fixed demo data and the server’s response encoder. Your translation library, IDs, and results will differ. A demo response is not a request to the running server.

`PING`

Check the connection. pong=true confirms a successful command.

Required permission none

Command / request

PING

Example response

OK pong=true

Try in Shell →

`SERVER INFO`

Inspect server version, protocol_version, and capabilities. Requires an authenticated connection.

Required permission server.get

Command / request

SERVER INFO

Example response

OK protocol_version=1 version="0.0.1" capabilities="help,auth,translation,read,search,live"

Try in Shell →

`TRANSLATION LIST`

List installed translation slugs. Use TRANSLATION LIST ALL to include the local catalog. This does not list your enabled account library.

Required permission translation.list

Command / request

TRANSLATION LIST

Example response

OK translations="WEB"

Try in Shell →

`ACCOUNT TRANSLATION LIST`

List editions enabled for the current account. ACCOUNT TRANSLATION ADD SLUG enables an installed edition; REMOVE disables it. Both require translation.list and obey account limits.

Required permission translation.list

Command / request

ACCOUNT TRANSLATION LIST

Example response

OK translations="WEB" count=1

Try in Shell →

`READ WEB 19 23 1`

Read one verse. Requires an enabled edition. Book may be a numeric ID or localized name; chapter:verse is also accepted.

Required permission translation.read

Command / request

READ WEB 19 23 1

Example response

OK translation="WEB" book=19 chapter=23 verse=1 text="The LORD is my shepherd; I shall lack nothing."

Try in Shell →

`READ WEB 19 117`

Read an entire chapter. The verses field counts VERSE records; END completes the response. Omit chapter to read a book.

Required permission translation.read

Command / request

READ WEB 19 117

Example response

OK translation="WEB" book=19 chapter=117 verses=2
VERSE text="Praise the LORD, all you nations! Extol him, all you peoples!"
VERSE text="For his loving kindness is great toward us. The LORD's faithfulness endures forever. Praise the LORD!"
END

Try in Shell →

`SEARCH WEB shepherd`

Search verse text in an enabled edition. results counts returned records. This fixture contains one match; the actual result set depends on the edition. The default cap is 100 results.

Required permission translation.search

Command / request

SEARCH WEB shepherd

Example response

OK translation="WEB" results=1
VERSE text="The LORD is my shepherd; I shall lack nothing."
END

Try in Shell →

`LIVE CREATE "Sunday Service"`

Create a running Live. Copy the returned id into subsequent commands and open /lives/LIVE_ID for the audience. Creation consumes one stored Live slot.

Required permission live.create

Command / request

LIVE CREATE "Sunday Service"

Example response

OK id="demoLive01" name="Sunday Service" paused=false status=running translations="web"

Try in Shell →

`LIVE LIST`

List accessible Lives. An empty result still has a count and an END marker.

Required permission live.list

Command / request

LIVE LIST

Example response

OK count=0
END

Try in Shell →

`LIVE demoLive01 STACK PUSH WEB 19 23 1`

Present a verse on a managed, running Live. The translation must be enabled. The response contains one VERSE record per selected translation.

Required permission live.update

Command / request

LIVE demoLive01 STACK PUSH WEB 19 23 1

Example response

OK event=verse translations=1
VERSE translation="WEB" reference="Psalms 23:1" text="The LORD is my shepherd; I shall lack nothing."
END

Try in Shell →

`LIVE demoLive01 CLEAR`

Clear the current viewer presentation without deleting the Live. A successful response has event=clear.

Required permission live.update

Command / request

LIVE demoLive01 CLEAR

Example response

OK event=clear

Try in Shell →

Complete command reference (Markdown)

The full reference includes account management, operator commands, arguments, Live secrets, stack operations, permissions, and lifecycle behavior.

Complete command reference (Markdown) ↗