cli-anything-calibre
A stateful CLI harness for Calibre e-book management. Wraps the real Calibre tools (
,
,
) 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:
bash
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)
bash
# 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
bash
# 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:
bash
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.
| Command | Description |
|---|
| Set active library path |
| Show library statistics (book count, formats, db size) |
| Verify library integrity using calibredb check_library |
Books
| Command | Description |
|---|
| List books with filtering and sorting |
| Search using Calibre query language |
| Add book files to library |
| Remove books (move to trash or permanent delete) |
| Show full metadata for a book |
| Export books to directory |
| Export each chapter as separate PDF (requires EPUB format) |
Meta
Metadata editing (wrap
).
| Command | Description |
|---|
| Get metadata (all or specific field) |
| Set a metadata field |
| Embed metadata into book files |
Formats
Format management (wrap
+
).
| Command | Description |
|---|
| List available formats for a book |
| Add a format to a book |
| Remove a format from a book |
convert <id> <input_fmt> <output_fmt>
| Convert book format |
Custom
| Command | Description |
|---|
| List all custom columns |
add <label> <name> <type>
| Create custom column |
| Delete custom column |
| Set custom field value |
Catalog
Catalog generation.
| Command | Description |
|---|
| Generate a catalog of the library (EPUB, CSV, or OPDS) |
Examples
Connect and List Books
Connect to your Calibre library and list books.
bash
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.
bash
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.
bash
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.
bash
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.
bash
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
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
| Field | Type | Description |
|---|
| text | Book title |
| text | Author names (&-separated) |
| text | Comma-separated tags |
| text | Series name |
| float | Position in series |
| float | Rating 1-5 |
| text | Publisher name |
| datetime | Publication date |
| text | Description/comments |
| text | Language codes |
| text | ISBN, ASIN, etc. () |
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: environment variable
Output Formats
All commands support dual output modes:
- Human-readable (default): Tables, colors, formatted text
- Machine-readable ( flag): Structured JSON for agent consumption
bash
# 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:
- Always use flag for parseable output
- Check return codes - 0 for success, non-zero for errors
- Parse stderr for error messages on failure
- Verify outputs exist after export/conversion operations
- Use flag or env to specify library path
- 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