shamela-kit 0.2.0

CLI and GUI toolkit for maintaining Shamela data directories

Shamela Kit

A CLI and native desktop GUI toolkit for maintaining local Shamela data directories.

Shamela Kit helps you manage custom books in your local Shamela installation without editing the official app code. It can inspect your data directory, import books from JSON/BOK/EPUB, export books to JSON, edit custom book metadata, attach online PDF links, remove custom books, and create explicit backups when you want them.

Disclaimer: This software is free and open source. It is intended for personal, educational, and archival workflows. Close Shamela before making write changes.

Development note: Shamela Kit was developed with AI-assisted coding. Changes are reviewed, tested, and maintained by the project author.

Screenshots

Features

• Native desktop GUI in Arabic by default, with English available from the Language menu.
• CLI for repeatable and scripted workflows.
• Works with Shamela's current Windows, macOS, and Linux data layout.
• Inspects a Shamela data directory and runs health checks for SQLite, Lucene, Java, and process safety.
• Lists and manages custom books in the reserved 900000001+ ID range.
• Imports one or more books from Shamela .bok, EPUB, or Shamela Kit JSON.
• Exports installed books to a JSON format that can be edited, backed up, or re-imported.
• Changes custom book category and author metadata.
• Links custom books to online PDFs, including Shamela-style multi-file PDF mappings.
• Optionally preserves sanitized EPUB formatting for headings, lists, emphasis, links, and tables.
• Removes custom books from SQLite and Lucene, with optional orphan-author cleanup.
• Creates and restores backups on demand. Backups are opt-in because fully downloaded Shamela libraries can be large.

Installation

Desktop app

Download the latest desktop build from GitHub Releases when packaged builds are available.

CLI package

For the CLI:

uv tool install shamela-kit

Requirements for Python installs:

• Python 3.14+
• Java 21 runtime for Lucene operations
• Java 21 compiler the first time the bundled Lucene bridge is compiled

Shamela Kit first tries Shamela's bundled Java runtime. If that is not available, set JAVA_HOME, SHAMELA_MANUAL_JAVA, or install Java 21 with your system package manager or mise.

Quick Start

1. Close Shamela.
2. Open Shamela Kit.
3. Confirm the data root points to your Shamela folder.
4. Run Doctor before making changes.
5. Import a book, edit metadata, link a PDF, or manage existing custom books.

Default Shamela roots:

• macOS: ~/Library/Application Support/Shamela
• Windows and Linux: the Shamela program folder when it contains database

You can also set custom paths with SHAMELA_DATA_ROOT, SHAMELA_RUNTIME_ROOT, --data-root, and --runtime-root.

CLI Examples

shamela-kit doctor
shamela-kit inspect
shamela-kit list
shamela-kit info 900000001

Import books:

shamela-kit import-bok ./book.bok --category-id 1
shamela-kit import-epub ./book.epub --category-id 1
shamela-kit import-epub ./book.epub --category-id 1 --preserve-formatting
shamela-kit add-json ./book.json
shamela-kit import-bok ./books/*.bok --category-id 1

Manage custom books:

shamela-kit set-category 900000001 2
shamela-kit set-author 900000001 "Author name"
shamela-kit export-json 900000001 -o book.json
shamela-kit remove-book 900000001 --backup

Attach PDF metadata:

shamela-kit set-pdf 900000001 https://archive.org/download/item/book.pdf
shamela-kit pdf-info 900000001
shamela-kit clear-pdf 900000001

Back up and restore explicitly:

shamela-kit backup --book-id 900000001
shamela-kit restore ./shamela-backup-YYYYMMDD-HHMMSS-ffffff --dry-run

Run shamela-kit --help for the full command list.

Safety Notes

• Write commands refuse to run while Shamela appears to be open. Use --force only when you know the detected process is unrelated.
• Backups are not automatic unless you pass --backup, because copying a complete Shamela library can be heavy.
• Deleting a custom book removes Shamela Kit's SQLite/Lucene records. Cached local PDF files are not deleted.
• Custom books should use IDs starting at 900000001.

Known Limitations

• EPUB import can preserve sanitized semantic HTML, but it does not import EPUB CSS or embedded images.
• Some BOK files do not contain a category that can be mapped automatically; pass --category-id.
• PDF links store metadata used by Shamela. They do not download PDF files by themselves.

Documentation

More detailed documentation lives in docs:

• CLI
• GUI
• EPUB formatting
• Data layout
• JSON format
• Development

Development

This project uses mise and uv.

mise install
mise run sync
mise run check

Useful tasks:

mise run cli -- doctor
mise run gui
mise run i18n
mise run build
mise run briefcase-build

The gui optional dependency is used for source/development environments and Briefcase packaging:

uv sync --extra gui

The project is intentionally independent from Shamela's bundled Python code. It writes the documented SQLite files directly and uses a small Java bridge for Lucene indexes because Shamela's current desktop data uses Lucene stores.

Acknowledgements

• BeeWare and Toga for the native GUI toolkit.
• Typer for the CLI.

License

GPL-3.0-only. See LICENSE.