How to use the Calibre E-book Library CLI agent skill

What the Calibre skill lets the agent do

The skill teaches an AI agent to operate Calibre, a desktop e-book manager, through a command-line tool called cli-anything-calibre. It wraps the real Calibre tools already on your computer: calibredb, ebook-convert and ebook-meta.

The agent can list and search books in your library, edit titles, authors, tags, series and ratings, convert a book between formats such as EPUB, MOBI and PDF, export chapters as separate PDFs, and generate catalogs. Results come back as structured JSON that the agent can read.

• Library: connect to a library, show statistics, and check its integrity
• Books: list, search, add, remove, show, and export books
• Metadata: get, set and embed metadata fields
• Formats: list, add, remove and convert formats
• Custom columns: list, add, remove and set values
• Catalog: generate a catalog as EPUB, CSV or OPDS

Check the requirements before you install

You need Python 3.10 or newer and the Calibre desktop application. Calibre is a hard requirement: the skill calls its tools, so it will not work without them. The source lists sudo apt-get install calibre for Debian and Ubuntu and brew install --cask calibre for macOS.

After installing Calibre, confirm that the three tools are on your PATH. If a command prints nothing or an error, the skill will not be able to find them.

• Python 3.10+
• Calibre desktop application (provides calibredb, ebook-convert and ebook-meta)
• Network access to GitHub for the pip install step

Install the cli-anything-calibre package

The CLI is installed as part of a Python package from the HKUDS/CLI-Anything GitHub repository, in the calibre/agent-harness folder. This step runs pip, which downloads code from GitHub, so only do it if you trust the source.

You can also install the skill files themselves. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, you can instead upload the ZIP under Settings, then Capabilities, then Skills.

Connect the skill to your library

Point the CLI at your Calibre library folder. The active library path is saved between sessions, so you normally only need to do this once. You can also set the CALIBRE_LIBRARY environment variable or pass a --library flag.

To check the CLI is working, ask for help or run a simple list command. Use the --json flag when an agent is reading the output.

• Session file: ~/.cli-anything-calibre/session.json
• Environment override: CALIBRE_LIBRARY

Trigger the skill with natural requests

You do not need to type commands yourself. Once the skill is installed, ask the agent in plain language about your library, and it can choose the matching commands. Name the book, author, format or outcome you want, and say whether you want changes made.

For bulk work, describe the rule and the scope. For example, ask the agent to list every book by one author, show the current tags, and then propose changes before applying them. Asking for a preview first is a good habit for any edit.

• Find every Asimov book tagged scifi in my Calibre library.
• Set the rating to 5 on book 42 and tell me what changed.
• Convert book 42 from EPUB to PDF and save it to my downloads folder.
• Export each chapter of book 42 as a PDF, first five chapters only.
• Generate an EPUB catalog of my library.

Search, edit and convert: examples

Searches use the Calibre query language, which supports fields such as author, title, tags, series and rating. Edits use meta set with a book ID, a field name and a value. Format conversion takes a book ID, an input format and an output format.

Chapter export only works on EPUB files, so the agent must convert a book to EPUB first if it is in another format. Remember that removing books and editing metadata or formats change files directly.

• Search examples: title:Foundation, rating:>3, has:cover, not:tags:fiction
• Editable fields include title, authors, tags, series, series_index, rating, publisher, pubdate, comments, languages and identifiers

Safety: back up, and know what the skill touches

The skill runs scripts and uses the network during installation. It modifies your library: removing books, editing metadata and changing formats alter files directly, and mistakes can be hard to undo. Make a complete backup of your Calibre library folder before you let an agent make bulk changes.

Test on a copy of a few books first. When you ask for edits, ask the agent to show the commands and the expected result before it runs them. Check the return code and confirm output files exist after exports or conversions, as the skill's own agent guidance recommends.

• Back up the whole library folder before bulk edits or removals
• Try the workflow on a small test library or a few books first
• Ask for a preview of changes before they are applied
• Check return codes and confirm exported or converted files exist