📚 lib-x

lib-x demo

View Demos & Previews

Full Demo:

lib-x-full-github-demo.webm

Previews:

• Features
• Installation
  • Prerequisites
  • Universal Installation
  • Platform-Specific Instructions
• Usage
  • Quick Start
  • Command-Line Options
  • Environment Variables
  • Examples & Workflows
• Configuration
  • Configuration File Location
  • Configuration Variables
• Extensions
• Frequently Asked Questions (FAQ)
• Contribution
• Support

• Multiple Launcher Support: Browse with fzf, rofi, or gum, all supporting rich previews.
• Deep Calibre Integration: Interface securely with your library via calibredb.
• Search & Filter: Search books using Calibre's native syntax, or browse directly by Authors, Series, Tags, Formats, Languages, Ratings, Publishers, and Identifiers.
• Personal Reading Lists: Track your reading journey with built-in user lists (Reading, Paused, Planning, Re-reading, Completed, Dropped, Docs).
• Extensive Book Actions: Directly from the terminal:
  • Read your books
  • Edit Metadata (Tags, Authors, Dates, etc.)
  • Convert formats (ebook-convert)
  • Polish books (ebook-polish)
  • View raw metadata
  • Open in Calibre's GUI Viewer (ebook-viewer)
• Bulk Add Books: Seamlessly add books from files or folders (integrates with fzf or yazi as a file chooser).
• Theming & Styling: Theming support through .theme extensions with Tokyo Night as the default theme.
• Multi-language Support: Loadable language files (.lang) to localize UI prompts and messages.
• Cover Art Previews: High-quality book cover image rendering directly in the terminal using chafa, icat, or imgcat.
• Custom Readers: Map specific formats (e.g., EPUB, PDF) to your preferred CLI/GUI reading apps.
• Scriptable Shortcuts: Bypass menus and jump straight to specific lists, searches, or actions using direct command-line flags.
• Stateful Sub-Shell Execution: Drop into a shell pre-loaded with environment variables of your currently selected book for custom scripting or manual database interactions.
• Desktop Integration: Generate a .desktop file to launch natively from application menus (Linux).
• Cache Management: Automatically caches your Calibre database as JSON for lightning-fast speeds, cleaning up stale previews and data automatically (Default: 7 days).
• OS Support: Works across Linux, macOS, Windows (via WSL/MSYS/Cygwin), and Android (Termux).
• Auto-Updater: Secure update checker that pulls the latest version from GitHub and shows you the diff before applying.
• Shell Completions: Includes tab completions for fish, bash, and zsh covering flags, custom categories, and book sorting options.

Required:

• calibre - Provides calibredb for database interactions.
• fzf - Main terminal launcher.
• jq - For rapid JSON database parsing.
• sh - Any POSIX-compliant shell (Bash, Zsh, Dash, etc.).
• Nerd Font - For the icons (Recommended: JetBrains Mono Nerd Font).

Optional (Highly Recommended for Full Functionality):

• Terminal File Explorers (For adding books): yazi or fzf
• Calibre CLI Tools: ebook-convert, ebook-polish, ebook-viewer, ebook-meta, ebook-edit (Usually bundled with Calibre).
• Alternate Launchers: rofi (for a desktop app experience) or gum (for styled TUI flows).
• Modern Terminal That Supports True Color: kitty, ghostty, wezterm, etc.
• Terminal Image Viewers (For Cover Art):
  • chafa (Cross-terminal)
  • icat (Recommended for Kitty and Ghostty)
  • imgcat (For iTerm2/WezTerm)
• Terminal QoL:
  • bat (Better paging and diff viewing)

Ensure ~/.local/bin exists and is added to your system's $PATH.

curl -sL "https://github.com/Benexl/lib-x/releases/download/v0.5.0/lib-x" -o ~/.local/bin/lib-x
chmod +x ~/.local/bin/lib-x

To uninstall, just run: rm ~/.local/bin/lib-x, then to remove its related data folders rm -r ~/.config/lib-x and rm -r ~/.cache/lib-x.

Note: I am not the one who maintains any of these packages and you should probably turn off auto updates in lib-x if using them.

yay -S lib-x-git

# or if you prefer paru

paru -S lib-x-git

nix profile install github:Benexl/lib-x

inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
  lib-x = {
    url = "github:Benexl/lib-x";
    inputs.nixpkgs.follows = "nixpkgs";
  };
}

You can opt to either use it via interactive menus or command-line shortcuts for scripting and keybinding.

lib-x [OPTIONS]
lib-x completions [--fish | --bash | --zsh | --help]

To launch the interactive terminal interface with your default settings, run:

lib-x

• -s, --search <term> : Prompt for (or immediately execute) a book search.
• -S, --sort-by <field> : Sort the books by a specific field (e.g., author, size, timestamp). Append _asc for ascending order (default is descending).
• -r, --no-of-random-books <num> : Display a specific number of random books from your library.

All these options can be paired with --cmd-exit (-ce) so that backing out of the menu exits the CLI entirely.

• --reading-list : Open your actively reading list.
• --recent : Show recently opened books.
• --paused : Open paused books.
• --rereading : Open books marked for re-reading.
• --planning : Open planned/to-read books.
• --completed : Open completed books.
• --docs : Open your documents list.
• --dropped : Open dropped/abandoned books.
• --all : Browse your entire Calibre library directly.
• --misc : Open the miscellaneous menu (Sync, Add books).

Can be paired with --book-skip (-bs) to auto-select the first result, and --book-exit (-be) to exit immediately after the action.

• --read : Open the selected book in your preferred reader.
• --edit-metadata : Start editing the metadata for a book.
• --remove-book : Delete a book from the library.
• --viewer : Open in the Calibre GUI ebook-viewer.
• --convert : Convert the book to another format.
• --edit-book : Open in the Calibre eBook Editor.
• --polish : Run ebook-polish on the selected book.
• --show-metadata : View the raw metadata (using ebook-meta).

• -l, --launcher <fzf|rofi|gum> : Override the default menu launcher.
• --preview : Enable the preview window (metadata).
• --no-preview : Disable the preview window.
• --preview-images : Enable the image preview (book covers).
• --no-preview-images : Disable the image preview.
• -d, --disown-reading-process : Detach the reading process from the terminal (default).
• -D, --no-disown-reading-process : Keep the reading process attached to the terminal session.
• --private : Do not update the recent history list when opening a book.

Note: You can find preconfigured rofi themes in the GitHub repo to elevate the desktop app experience!

• --rofi-theme-main <path>
• --rofi-theme-preview <path>
• --rofi-theme-prompt <path>
• --rofi-theme-confirm <path>
• --rofi-theme-pager <path>

• -x, --extension <ext> : Load a specific extension file.
• -xargs, --extension-arguments <args> : Pass arguments to a loaded extension.
• -e, --edit-config : Open the lib-x configuration file in your $EDITOR.
• -U, --update : Check for and apply the latest script update from GitHub.
• -E, --generate-desktop-entry : Print a .desktop application entry to stdout.
• -v, --version : Print version information and exit.
• -h, --help : Show the help message and exit.
• --config-write : Write the current runtime config to the config file.

Almost all CLI options can be permanently set in ~/.config/lib-x/config or overridden using environment variables.

• LIB_X_LAUNCHER (e.g., fzf, rofi, gum)
• LIB_X_CALIBRE_LIBRARY_PATH (e.g., $HOME/Documents/Calibre Library)
• LIB_X_PREVIEW_ENABLE (true or false)
• LIB_X_PREVIEW_IMAGES_ENABLE (true or false)
• LIB_X_PREVIEW_IMAGES_RENDERER (chafa, icat, imgcat)
• LIB_X_FILE_EXPLORER (fzf, yazi)

Hello world (Save config)

# always put --config-write at the end to save the runtime config
LIB_X_PREVIEW_IMAGES_RENDERER=icat lib-x --preview --preview-images --config-write

Desktop App Launcher

Launch lib-x as a graphical application using Rofi (great with keybindings!).

lib-x --launcher rofi --preview --preview-images --disown-reading-process

Custom Book Reader Mapping

You want EPUBs to open in zathura and PDFs to open in evince. Set this in your config or env:

LIB_X_READER="epub:zathura,pdf:evince" lib-x --read

Jump straight to your current reads

lib-x --reading-list --cmd-exit

Find a specific author and exit menu on back

lib-x -s "Isaac Asimov" --cmd-exit

Create a desktop entry

lib-x -E > ~/.local/share/applications/lib-x.desktop

Shell completions (Fish)

lib-x completions --fish > ~/.config/fish/completions/lib-x.fish

By default, the main configuration file is located at:

~/.config/lib-x/config

(Note: It respects the $XDG_CONFIG_HOME environment variable if set).

You can open it directly using the CLI:

lib-x --edit-config

(Note: Advanced Fzf and Gum styling parameters are also exposed in the config file. See the generated config file for full default strings).

lib-x supports extensions to add languages, themes, or override functionality. Extensions are standard shell scripts loaded from ~/.config/lib-x/extensions/.

• Languages: Add localizations by editing langs/default.lang (e.g., swap out TXT_MENU_MAIN_SEARCH="Search" to your native language).
• Themes: Tweak terminal colors by editing themes/default.theme (defines $THEME_HEADER_COLOR, $THEME_FZF_ICON_COLOR_PRIMARY, etc.).
• Autoloading: Add any custom .sh script names to CONFIG_AUTOLOADED_EXTENSIONS="custom.sh" to have them sourced at runtime.

Pull requests are highly welcome! :)

If you enjoy using lib-x and want to support its ongoing development, consider leaving a Star on GitHub!