cli-anything-calibre

name cli-anything-calibre description Command-line interface for Calibre - A stateful CLI harness for e-book library management, metadata editing, and format conversion wrapping the real Calibre tools (calibredb, ebook-convert, ebook-meta)... 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. Command Description connect <path> Set active library path info Show library statistics (book count, formats, db size) check Verify library integrity using calibredb check_library Books Book operations (wrap calibredb ). Command Description list List 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 ). Command Description 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 ). Command Description 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 ). Command Description list List 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. Command Description 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 Field Type Description title text Book title authors text Author names (&-separated) tags text Comma-separated tags series text Series name series_index float Position in series rating float Rating 1-5 publisher text Publisher name pubdate datetime Publication date comments text Description/comments languages text Language codes identifiers text ISBN, 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: Always use --json 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 --library flag or CALIBRE_LIBRARY 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