mybible-cli.py is a command line utility to query MyBible.zone modules. It has been inspired by diatheke – a command line utility for Crosswire Sword modules.
The main goal of mybible-cli.py is only to get the required text, not to perform search or analyze the matched data, as there are other tools that can do that. The output of the tool can be piped, so there are limitless possibilities to do whatever is needed with the output text.
Though MyBible module format specification describes more than one module type, the script works only with Bible modules. Any other modules (commentaries, devotions, plans, etc.) will be invisible to the script. A good place to get modules is ph4.org website.
mybible-cli.py is a self-contained script with no dependencies on anything other than Python 3.12. No installation is required, the script can run from anywhere. If you find it useful, though, it might be better to copy or symlink it anywhere in your $PATH (%PATH%).
Here's one of the ways to do it:
git clone https://github.com/kosivantsov/mybible-cli.git
cd mybible-cli
chmod +x mybible-cli
ln -s $(pwd)/mybible-cli.py $HOME/bin/mybible-cliThis way you could run it by simply invoking mybible-cli, and it would update automatically when you pull changes in your local copy.
If you use MS Windows and don't have Python installed, it's still possible to use the script. Download the Windows build (look for a file named mybible-cli.zip),
unpack it somewhere, and run mybible-cli.exe in the unpacked folder. When the zip is unpacked, you'll find mybible-cli.exe and a subfolder named _internal. Both are needed for the program to run.
For the program to be useful (whether as a script or a Windows executable), you must have at least one MyBible module.
This script/application can be used directly on the command line, or used in other scripts and applications to get Bible text. Below is a brief overview of its usage on the command line.
When run for the first time (unless -h, --help, or --helpformat arguments were used), it will ask to specify a path to the folder with MyBible modules. The modules folder can be changed at any time using the -p, --path argument.
When run for the first time with --gui, a GUI filechooser will open to select the modules folder.
Running the script without any arguments will produce a short help message. Run with -h, --help, --helpfomat to get more details.
Long help message
Options:
-h, --help
Shows help message and exits
-p PATH, --path PATH
Specify the path to the folder with MyBible modules
-L, --list-modules
List available MyBilbe modules
-m MODULE_NAME, --module-name MODULE_NAME
Name of the MyBible module to use
-r REFERENCE, --reference REFERENCE
Bible reference to output
-a ABBR, --abbr ABBR
Get Bible book names and abbreviations from a non-default file.
With '--abbr uk' a file named 'uk_mapping.json' located in the configuration folder will be used
-A, --self-abbr
Get Bible book names and abbreviations from the module itself
-f FORMAT, --format FORMAT
Format output with %-prefixed format sting.
Available placeholders: %f, %a, %c, %v, %t, %T, $z, %A, %Z, %m
-F SAVE_FORMAT, --save-format SAVE_FORMAT
Specified format string will be applied and saved as default.
--helpformat
Detailed info on the format string
--noansi
Clears out any ANSI escape sequences in the Bible verses output (if %A or %Z were used in the format string)
--open-config-folder
Opens the config folder
--open-module-folder
Opens the folder with MyBible modules
--j2t <JSON_FILE>, --json-to-tsv <JSON_FILE>
Converts a json file to tsv (to edit a mapping file)
--check-tsv <TSV_FILE>
Reports duplicates in the specified tsv file
--t2j <TSV_FILE>, --tsv-to-json <TSV_FILE>
Converts a tsv file to json (to use as a mapping file)
--gui
Outputs text in a GUI window
The script can list all the installed modules with -L. The list will be sorted by language and will include Bible modules only. When first invoked, it would take a few moments to query each file and get the required info. That info is then hashed and reused until modules are changed.
The most common usage would be calling the script with a module name and a reference to get the required text:
mybible-cli -m "KJV+" -r "Jn 11:35"
If a parameter passed to the script contains a space or a character that can have a special meaning for the shell, it needs to be quoted.
The script understands only the colon Bible notation without letters and parenthesis in the chapter and verse part. Chapter and verse numbers could be omitted to output an entire book or chapter. Blocks should be separated by commas or semicolons. Ranges are marked with a minus. Spaces in ranges are permitted. Periods will be ignored.
If -m "<MODULE_NAME>" is omitted in the command, the script will use the last used module.
mybible-cli -m "KJV+" -r "Jn 11:35" --gui will output the text in a GUI window where it is possible to view the requested text in any of the installed modules without running the command again.
The script outputs each verse on a separate line and formats it using a format string with %-prefixed placeholders.
To learn what each placeholder means, run mybible-cli --helpformat.
The default format is %f %c:%v: %t (%m) (full book name, chapter:verse: text without most MyBible markup, module name in parenthesis): John 11:35: Jesus wept. (KJV+).
A format string specified with -f is applied only once. With -F, the specified format string will be saved as default and used when no format string is given explicitly.
Text of the reference can be output in five different ways:
%T- raw text with all the markup as in the module itself%t- plain text, no Strong's numbers, no other markup, but with line breaks and indentations as marked in the module; with notes%z– the same as above, but without line breaks and indentations marked in the module; notes removed%A– MyBible markup is converted to ANSI escape sequences for pretty output in the terminal. Includes Strong's numbers%Z– the same as above, but without Strong's numbers
If you need Strong's numbers in the output, but don't want to get the escape sequences (for instance, when you pipe output of the script), there is an option--noansi. It has no effect on the output when the text is not formatted with%Aor%Z.
The GUI output can be formatted too, either on the command line or by providing the format string in the dedicated dialog box. The format string specified in GUI will be saved as default.
Bible book names and abbreviations are looked up in a list provided within the script. During the first run, the list is saved as mapping.json in the configuration directory and could be used to create custom lookup lists.
If you want to use book names and abbreviations from the module itself, run the script with the -A argument. To use a non-default lookup list, use -a prefix. In that case, the script will try to use prefix_mapping.json in the config folder.
prefix can be an arbitrary string but a file name with that prefix should exist, otherwise the default lookup file is used.
The script has three arguments to help with creating custom files to look up Bible names:
--j2t,--json-to-tsv: converts json to tsv which can be open and edited in a spreadsheet application--t2j,--tsv-to-json: converts tsv with edited data to json to be used with-largument--check-tsv: finds and reports duplicates in a tsv file
json-to-tsv and tsv-to-json output the converted file in the same location as the input file, with the same file name but different extension. No check for file extensions or data is performed during conversion, so it's possible to convert wrong data to wrong formats.
The script allows opening its config folder and the folder with the MyBible modules in the default file manager. There are two arguments for that:
--open-config-folder--open-module-folder
This script's UI strings can be localized. The script will read its localization from a file l10n/<lang>.properties located in the configuration folder, where <lang> is a language code. If there is a .properties file with the same filename as the system's locale language code that file will be used. Any strings missing from the file will be output as they are hardcoded in the script. At the moment, only en.properties and uk.properties are available. Localization files have to be copied manually.
The script doesn't require to be built on GNU/Linux and macOS since these OSes have Python installed by default. On Windows with Python installed the script can run as is, without building.
If you need to build a binary that will run without Python being installed on your system, it can be done with pyinstaller. Included you'll find the spec file. pyinstaller is not needed for the script to function,
it's only purpose is to compile the script into a binary.
- Create a new venv:
python3.12 -m venv $HOME/pyinstaller-venv - Activate the venv:
source $HOME/pyinstaller-venv/Scripts/activateorcd $HOME; .\pyinstaller-venv\Scripts\activate - Install pyinstaller:
pip3 install pyinstaller - Go to
mybible-clisource folder and build the binary:cd src/mybible-cli; pyinstaller mybible-cly.spec
On Windows you may also use buildWindows.cmd that automates the process.
A folder with the executable and its dependencies will be found under dist subfolder.