What is the Calibre CLI Tool?

The Calibre CLI Tool is a command-line interface that wraps Calibre's core functionalities for managing e-books, allowing users to perform library operations, edit metadata, and convert formats.

What are the prerequisites for using this tool?

You need Python 3.10 or higher and Calibre installed on your system to use the Calibre CLI Tool.

Can I use this tool without a graphical interface?

Yes, this tool is designed for command-line use, making it suitable for environments without a graphical interface.

What types of operations can I perform with this CLI?

You can manage your library, add or remove books, edit metadata, and convert e-book formats using this CLI.

Is there an interactive mode available?

Yes, the CLI includes an interactive REPL mode that allows for command execution with features like tab-completion and command history.

Calibre CLI Tool

Name: Calibre CLI Tool
Availability: InStock
Author: hkuds

Free

Manage your e-book library from the command line.

by hkuds46.9k stars on hkuds/cli-anything

6 views

Updated Aug 3, 2026

Get this skill

Free · Opens the source repo

What Calibre CLI Tool does

The Calibre CLI Tool provides a structured command-line interface for managing e-books using Calibre's powerful features. This skill wraps the core Calibre tools—calibredb, ebook-convert, and ebook-meta—to enable seamless library management, metadata editing, and format conversion. With this CLI, users can connect to their Calibre library, perform operations like adding or removing books, and edit metadata fields all through a consistent command-line interface.

The tool supports an interactive REPL mode, allowing users to execute commands with tab-completion and command history, enhancing the user experience. Users can leverage the library management commands to connect to their library, check its integrity, and gather statistics. Book operations include listing, searching, and exporting books, while metadata editing allows for precise control over book attributes such as title, author, and tags.

For those needing to convert e-book formats, the CLI provides commands to convert between various formats, ensuring compatibility across different devices and platforms. Additionally, users can generate catalogs of their library in multiple formats, making it easier to share or archive their collections. This tool is ideal for developers and designers who require a robust solution for managing e-books programmatically or through scripts.

When to use it

Use this tool when you need to automate e-book management tasks or when working in environments without a graphical interface.

When not to use it

This skill may not be suitable for users who prefer a graphical user interface or those who do not have Calibre installed.

What you can build with it

Automate E-Book Management

Use the Calibre CLI Tool to script repetitive tasks such as adding new e-books or updating metadata, streamlining your workflow.

Generate E-Book Catalogs

Quickly generate catalogs of your e-book library in various formats for sharing or archiving purposes.

Convert E-Book Formats

Easily convert e-books between formats like EPUB and PDF to ensure compatibility with different devices.

How to install Calibre CLI Tool

View source

1. Install with the skills CLI

npx skills add hkuds/cli-anything/skills --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by hkuds

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)

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

Frequently asked questions about Calibre CLI Tool

Similar skills

PDFtk Server

Command-line tool for comprehensive PDF manipulation.

PDF Processing

Comprehensive tools for manipulating PDF files.

PDF Processing

Comprehensive tools for managing PDF files.

Mac Storage Cleaner

Reclaim disk space safely and transparently on macOS.

PDF Processing

Comprehensive tools for managing PDF files.

Screenshot Capture

Capture screenshots across different platforms easily.