mcpField
C
cli-anything-calibre

cli-anything-calibre

github.com/hkudsDocuments57.6k330 installsUpdated 5w ago
Repository

About cli-anything-calibre

cli-anything-calibre is a stateful command-line interface for Calibre library management, metadata editing, and e-book conversion. It wraps Calibre's tools with structured output for scripts and AI agents; Calibre must be installed separately.

Key features

  1. 01Connect to and inspect libraries
  2. 02Search, add, export, and remove books
  3. 03View and edit book metadata
  4. 04Manage formats and convert books
  5. 05Generate EPUB, CSV, or OPDS catalogs
  6. 06Human-readable and JSON output

Use cases

  1. 01Search a library with Calibre queries
  2. 02Update book metadata in batches
  3. 03Convert books to another format
  4. 04Export EPUB chapters as separate PDFs

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/hkuds/cli-anything --skill cli-anything-calibre

After installing, type/cli-anything-calibrein Claude Code to confirm it loaded.

Details

From the project README

cli-anything-calibre

A stateful CLI harness for Calibre e-book management. Wraps the real Calibre tools (calibredb, ebook-convert, ebook-meta) to give AI agents and scripts a clean, structured interface for library operations, metadata editing, and format conversion.

Installation

This CLI is installed as part of the cli-anything-calibre package:

pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness

Prerequisites:

  • Python 3.10+
  • Calibre must be installed on your system (hard dependency)
# Debian/Ubuntu
sudo apt-get install calibre

# macOS
brew install --cask calibre

# Verify tools are in PATH
which calibredb
which ebook-convert
which ebook-meta

Usage

Basic Commands
# Show help
cli-anything-calibre --help

# Start interactive REPL mode
cli-anything-calibre

# Connect to a Calibre library
cli-anything-calibre library connect ~/Calibre\ Library

# Run with JSON output (for agent consumption)
cli-anything-calibre --json books list
REPL Mode

When invoked without a subcommand, the CLI enters an interactive REPL session:

cli-anything-calibre
# Enter commands interactively with tab-completion and history
# Use 'help' to see available commands
# Use 'quit' or 'exit' to leave

Command Groups

Library

Library management commands.

CommandDescription
connect <path>Set active library path
infoShow library statistics (book count, formats, db size)
checkVerify library integrity using calibredb check_library
Books

Book operations (wrap calibredb).

CommandDescription
listList books with filtering and sorting
search <query>Search using Calibre query language
add <files>Add book files to library
remove <ids>Remove books (move to trash or permanent delete)
show <id>Show full metadata for a book
export <ids>Export books to directory
export-chapters <id>Export each chapter as separate PDF (requires EPUB format)
Meta

Metadata editing (wrap calibredb set_metadata).

CommandDescription
get <id> [field]Get metadata (all or specific field)
set <id> <field> <value>Set a metadata field
embed <ids>Embed metadata into book files
Formats

Format management (wrap calibredb + ebook-convert).

CommandDescription
list <id>List available formats for a book
add <id> <file>Add a format to a book
remove <id> <fmt>Remove a format from a book
convert <id> <input_fmt> <output_fmt>Convert book format
Custom

Custom columns (wrap calibredb).

CommandDescription
listList all custom columns
add <label> <name> <type>Create custom column
remove <label>Delete custom column
set <id> <label> <value>Set custom field value
Catalog

Catalog generation.

CommandDescription
catalog <output>Generate a catalog of the library (EPUB, CSV, or OPDS)

Examples

Connect and List Books

Connect to your Calibre library and list books.

cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list
# Or with JSON output
cli-anything-calibre --json books list --search "author:asimov"
Search and Filter

Search books using Calibre query language.

cli-anything-calibre books search "title:Foundation"
cli-anything-calibre books search "author:asimov and tags:scifi"
cli-anything-calibre books search "rating:>3"
Metadata Editing

Set metadata fields on books.

cli-anything-calibre meta set 42 title "New Title"
cli-anything-calibre meta set 42 series "Foundation"
cli-anything-calibre meta set 42 series_index 1
cli-anything-calibre meta set 42 tags "scifi,classic"
cli-anything-calibre meta set 42 rating 5
Format Conversion

Convert between e-book formats.

cli-anything-calibre formats convert 42 EPUB MOBI
cli-anything-calibre formats convert 42 EPUB PDF --output /tmp/book.pdf
Export Chapters as PDFs

Export each chapter of an EPUB as a separate PDF file.

cli-anything-calibre books export-chapters 42 --to-dir ./pdfs
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs --chapters 1-5

Calibre Query Language

Used with books search and books list --search:

author:asimov                    # Author contains "asimov"
title:"Foundation"               # Title phrase
tags:fiction                     # Tag match
rating:>3                        # Rating greater than 3
series:"Foundation"              # Series match
pubdate:[2020-01-01,2021-12-31]  # Date range
identifiers:isbn:1234567890      # Specific identifier
has:cover                        # Has cover image
not:tags:fiction                 # Negation
author:asimov and tags:scifi     # Boolean AND

Key Metadata Fields

FieldTypeDescription
titletextBook title
authorstextAuthor names (&-separated)
tagstextComma-separated tags
seriestextSeries name
series_indexfloatPosition in series
ratingfloatRating 1-5
publishertextPublisher name
pubdatedatetimePublication date
commentstextDescription/comments
languagestextLanguage codes
identifierstextISBN, ASIN, etc. (type:value)

Supported Formats

Input: EPUB, MOBI, AZW, AZW3, PDF, HTML, DOCX, ODT, FB2, TXT, RTF, LIT, and more

Output (conversion): EPUB, MOBI, AZW3, PDF, HTML, DOCX, TXT, and more

State Management

The CLI maintains session state with:

  • Session file: ~/.cli-anything-calibre/session.json
  • Library path persistence: Active library is saved across sessions
  • Environment override: CALIBRE_LIBRARY environment variable

Output Formats

All commands support dual output modes:

  • Human-readable (default): Tables, colors, formatted text
  • Machine-readable (--json flag): Structured JSON for agent consumption
# Human output
cli-anything-calibre books list

# JSON output for agents
cli-anything-calibre --json books list

For AI Agents

When using this CLI programmatically:

  1. Always use --json flag for parseable output
  2. Check return codes - 0 for success, non-zero for errors
  3. Parse stderr for error messages on failure
  4. Verify outputs exist after export/conversion operations
  5. Use --library flag or CALIBRE_LIBRARY env to specify library path
  6. Chapter export requires EPUB format - convert first if needed

More Information

  • Full documentation: See README.md in the package
  • Architecture SOP: See CALIBRE.md in the agent-harness directory
  • Test coverage: See test_core.py and test_full_e2e.py in the tests directory
  • Methodology: See HARNESS.md in the cli-anything-plugin

Version

1.0.0

Comments

Markdown supported