Shell for TequilaCat BookReader: A Lightweight CLI for Managing Your eBooks

Build a Custom Shell for TequilaCat BookReader — Tips & ShortcutsTequilaCat BookReader is a lightweight open-source e-book viewer focused on simplicity, speed, and keyboard-driven navigation. For power users who prefer a terminal-first workflow, building a custom shell around TequilaCat can streamline book management, automate common tasks, and integrate the reader into larger text-processing pipelines. This article walks through the design, implementation, and useful shortcuts for a custom shell tailored to TequilaCat BookReader.

---

Why build a custom shell?

A purpose-built shell can:

• Speed up repetitive tasks like opening specific books, searching collections, or jumping to annotations.
• Expose automation hooks so you can batch-convert, reflow, or reorganize your library.
• Provide consistent keyboard-driven workflows, reducing reliance on a mouse and GUI dialogs.
• Integrate TequilaCat with other tools (pdf processors, note-taking apps, sync scripts).

---

Design goals

Before coding, define goals that keep the shell focused:

• Minimal dependencies: keep it runnable on most Unix-like systems.
• Scriptable architecture: every command should be usable from scripts.
• Extensible command set: allow user-defined aliases and plugins.
• Clear, consistent keybindings: mirror TequilaCat’s navigation where possible.

---

Components of the shell

A robust shell for TequilaCat typically includes:

• Command parser and REPL loop
• Library index (simple SQLite or JSON)
• Book metadata extractor (title, author, format, path)
• Shortcuts and keybindings mapper
• Hooks for launching TequilaCat with specific options (page, theme)
• Plugin interface for custom commands

---

Choosing a language

Good choices:

• Python — batteries included, easy SQLite/JSON handling, fast prototyping.
• Go — single binary distribution, good concurrency, native performance.
• Rust — safe and fast, excellent for CLI tools but longer development time.
• Bash — fine for small wrappers, but limited for complex logic.

Example here assumes Python 3.10+ using argparse, sqlite3, and subprocess.

---

Minimal architecture (example)

• ~/.tequilacat-shell/
  • config.json — user settings, aliases, keybindings
  • library.db — SQLite index of books
  • plugins/ — executable scripts for extendability
  • bin/teq-shell — main REPL launcher

---

Building the library index

Index your books into an SQLite database with columns: id, title, author, path, format, added_at, last_opened. Use file discovery to scan common directories and extract metadata from filenames or embedded metadata (for EPUB/MOBI/PDF).

Python snippet (discovery + insert):

#!/usr/bin/env python3 import sqlite3, os, time DB = os.path.expanduser("~/.tequilacat-shell/library.db") conn = sqlite3.connect(DB) c = conn.cursor() c.execute("""CREATE TABLE IF NOT EXISTS books (     id INTEGER PRIMARY KEY,     title TEXT,     author TEXT,     path TEXT UNIQUE,     fmt TEXT,     added_at REAL,     last_opened REAL )""") def add_file(path):     fmt = os.path.splitext(path)[1].lower().lstrip('.')     title = os.path.splitext(os.path.basename(path))[0]     now = time.time()     c.execute("INSERT OR IGNORE INTO books (title,author,path,fmt,added_at) VALUES (?,?,?,?,?)",               (title, None, path, fmt, now))     conn.commit() for root in ["~/books","~/Downloads"]:     root = os.path.expanduser(root)     for dirpath,_,files in os.walk(root):         for f in files:             if f.lower().endswith(('.epub','.pdf','.mobi')):                 add_file(os.path.join(dirpath,f)) conn.close() 

---

Command set and examples

Design commands to be short and scriptable:

• open — open book in TequilaCat
• search — search titles/authors
• recent — list recently opened books
• tag — add tags to books (store in separate table)
• convert — call external converters (Pandoc/Calibre)
• notes — open annotations file in $EDITOR
• shell-aliases and macros for multi-step tasks

Example: open command launching TequilaCat at a page or with a theme:

import subprocess, shlex def open_book(path, page=None, theme=None):     cmd = ["tequilacat", path]     if page:         cmd += ["--page", str(page)]     if theme:         cmd += ["--theme", theme]     subprocess.run(cmd) 

---

Keybindings and shortcuts

Map REPL keys to frequent actions to speed navigation. Keep them mnemonic:

• o — open (prompt for id)
• s — search
• r — recent
• n — notes
• t — tag
• q — quit

Support combo keys for modifiers; use curses or prompt_toolkit for richer UI and key handling.

---

Plugins and extensibility

Allow any executable in plugins/ to be callable from the shell. Provide environment variables for context (BOOK_ID, BOOK_PATH). Example plugin contract:

• Plugin should be executable.
• Read BOOK_PATH from env.
• Output status lines to stdout for the shell to display.

This makes it easy to add integrations (send highlights to Obsidian, run OCR, push to Kindle).

---

Useful automation recipes

• Batch convert all EPUB to MOBI using Calibre’s ebook-convert.
• Export a reading list CSV for import into other apps.
• Sync read progress to a remote server via rsync or Git.
• Auto-generate bibliographies from metadata using BibTeX.

Example batch convert:

for p in ~/.tequilacat-shell/epubs/*.epub; do   out="${p%.epub}.mobi"   ebook-convert "$p" "$out" done 

---

UX considerations

• Provide sensible defaults but let users override via config.json.
• Keep commands idempotent where possible.
• Offer clear error messages and help text.
• Support fuzzy search for forgiving queries (fzf, rapidfuzz).

---

Example user workflow

1. Launch teq-shell.
2. Press s and type “Pratchett” to filter Terry Pratchett titles.
3. Press o to open selected book; it opens in TequilaCat at last saved page.
4. Press n to open notes and jot a quick annotation.
5. Tag the book “series:Discworld” for later grouping.

---

Testing and distribution

• Create unit tests for the parser and database interactions.
• Package as a single Python wheel or create a Go single binary.
• Provide a simple installer script that creates ~/.tequilacat-shell, copies default config, and sets up a system path entry.

---

Tips & Shortcuts summary

• Use fuzzy search for fast discovery.
• Map single-letter keys in the REPL for common commands.
• Keep a metadata index to enable filtering and automation.
• Use plugins to delegate heavy tasks and keep the core lightweight.
• Integrate with converters (Calibre, Pandoc) for format flexibility.

---

Building a custom shell for TequilaCat BookReader turns a simple reader into a central piece of a keyboard-driven reading workflow. Start with a minimal index and a few core commands, then grow features as your patterns emerge.