calibre-cli

Automation-friendly CLI wrapper for calibre ebook management.

Calibre ships with powerful command-line tools (calibredb, ebook-convert, ebook-meta, etc.), but they produce unstructured, human-oriented text output that is difficult for programs to consume. calibre-cli wraps these tools and exposes a single calibre-cli CLI command that returns structured JSON for every operation -- making it straightforward for automation tools, scripts, and automation pipelines to manage local calibre libraries.

Status

calibre-cli is currently a 0.1.0 beta. The core command groups and mocked unit test suite are implemented. Optional integration tests require a local calibre installation. CI runs the default unit test suite and package build.

See CHANGELOG.md for release notes.

Features

Unified JSON output for all operations ({success, data, error, meta})
Machine-readable error codes with deterministic exit codes
11 command groups covering books, metadata, formats, libraries, tags, full-text search, configuration, devices, server lifecycle, plugins, and diagnostics
Pagination support for book listings
Multi-library configuration with named aliases
Online metadata fetching and batch operations
Format conversion, polishing, and export
Catalog generation, custom columns, saved searches, and guarded database restore/clone operations
Remote calibre Content Server library options
Device, server, plugin, and debug wrappers for automation workflows
Full-text search management
Zero dependency on calibre's internal Python API -- communicates entirely via subprocess

Prerequisites

Python >= 3.10
calibre installed with its CLI tools available on PATH:
- calibredb
- ebook-convert
- ebook-meta
- fetch-ebook-metadata
- ebook-polish
Optional wrapper targets for advanced commands:
- calibre-server
- calibre-debug
- calibre-customize
- configured calibre_device entrypoint for device workflows

Verify calibre is available:

calibredb --version

Installation

Install from PyPI:

pipx install calibre-cli

Or with pip:

pip install calibre-cli

Development Setup

For local setup, unit tests, running without installation, and optional real-calibre integration tests, see Development.

Quick Start

Check your environment

calibre-cli doctor

{
  "success": true,
  "data": {
    "calibre_version": "7.6.0",
    "calibredb_path": "calibredb",
    "ebook_convert_path": "ebook-convert",
    "default_library": "/Users/me/Calibre Library",
    "libraries": {
      "main": "/Users/me/Calibre Library"
    }
  }
}

Register a library

calibre-cli config add-library main "/Users/me/Calibre Library"

{
  "success": true,
  "data": {
    "name": "main",
    "path": "/Users/me/Calibre Library",
    "is_default": true
  }
}

List books

calibre-cli book list --library main --limit 3

{
  "success": true,
  "data": {
    "books": [
      {"id": 1, "title": "The Pragmatic Programmer", "authors": "David Thomas & Andrew Hunt", "tags": "programming,software", "formats": "EPUB,PDF"},
      {"id": 2, "title": "Designing Data-Intensive Applications", "authors": "Martin Kleppmann", "tags": "databases,distributed-systems", "formats": "EPUB"},
      {"id": 3, "title": "Structure and Interpretation of Computer Programs", "authors": "Harold Abelson & Gerald Jay Sussman", "tags": "cs,lisp", "formats": "PDF"}
    ]
  },
  "meta": {
    "total": 142,
    "offset": 0,
    "limit": 3,
    "library": "/Users/me/Calibre Library",
    "elapsed_ms": 320
  }
}

Get book details

calibre-cli book get 42

{
  "success": true,
  "data": {
    "id": 42,
    "title": "Clean Code",
    "authors": ["Robert C. Martin"],
    "publisher": "Prentice Hall",
    "tags": ["programming", "best-practices"],
    "languages": ["eng"],
    "identifiers": {"isbn": "9780132350884"},
    "comments": "A handbook of agile software craftsmanship."
  }
}

Add a book

calibre-cli book add /path/to/book.epub

{
  "success": true,
  "data": {
    "added": [{"id": 143}],
    "count": 1
  }
}

Update metadata

calibre-cli metadata set 42 --field title:"Clean Code, 2nd Edition" --field tags:"programming,refactoring"

{
  "success": true,
  "data": {
    "book_id": 42,
    "updated_fields": ["title", "tags"]
  }
}

Convert format

calibre-cli format convert /path/to/book.epub --to pdf

{
  "success": true,
  "data": {
    "input": "/path/to/book.epub",
    "output": "/path/to/book.pdf",
    "format": "pdf"
  }
}

Command Reference

Global Options

Option	Description
`--library NAME_OR_PATH`	Library path or configured name
`--username USER`	Username for calibre Content Server libraries
`--password PASSWORD`	Password for calibre Content Server libraries
`--password-file FILE`	Read Content Server password from a file
`--password-stdin`	Read Content Server password from stdin
`--timeout SECONDS`	Network timeout for calibre Content Server libraries
`--verbose`	Enable verbose logging
`--version`	Show version and exit

`doctor`

Check calibre installation and library availability.

calibre-cli doctor

`book` -- Book Management

Command	Description
`book list`	List books with optional search, sorting, and pagination
`book get BOOK_IDS`	Get full details for one or more books (comma-separated IDs)
`book add PATH`	Add a book file or directory to the library
`book remove IDS`	Remove books by comma-separated IDs
`book search QUERY`	Search books using calibre search syntax
`book export IDS`	Export books to a directory

book list options: --search, --fields, --sort-by, --sort-order, --limit, --offset

book add options: --title, --authors, --tags, --isbn, --series, --series-index, --cover, --allow-duplicates, --recurse

book export options: --to-dir, --formats, --single-dir

`metadata` -- Metadata Operations

Command	Description
`metadata get BOOK_ID`	Get metadata for a book
`metadata set BOOK_ID`	Set metadata fields on a book
`metadata custom set BOOK_ID COLUMN VALUE`	Set a custom column value
`metadata cover fetch OUTPUT`	Fetch a cover image from online metadata sources
`metadata cover set BOOK_ID COVER_PATH`	Set a book cover
`metadata cover export BOOK_ID OUTPUT`	Export a book cover
`metadata batch-set`	Batch update metadata on multiple books from JSON
`metadata fetch`	Fetch metadata from online sources (by ISBN, title, or author)
`metadata embed IDS`	Embed calibre metadata into book files

metadata set options: --field KEY:VALUE (repeatable), --title, --authors, --tags, --rating, --from-json

metadata fetch options: --isbn, --title, --authors, --apply-to BOOK_ID

`format` -- Format Management

Command	Description
`format list BOOK_ID`	List available formats for a book
`format add BOOK_ID PATH`	Add a format file to a book
`format remove BOOK_ID FMT`	Remove a format from a book
`format convert SOURCE --to FMT`	Convert a book to another format
`format convert-options SRC_FMT TARGET_FMT`	Return ebook-convert help for option discovery
`format polish SOURCE`	Polish an ebook (EPUB/AZW3/KEPUB)
`format check SOURCE`	Run ebook quality checks
`format report SOURCE`	Generate ebook quality report
`format stats SOURCE`	Generate ebook statistics

format convert options: --to (required), --output, --output-profile, --option KEY=VALUE, --extra-arg=--RAW-FLAG

format polish options: --output, --embed-fonts, --subset-fonts, --compress-images, --cover, --jacket, --remove-jacket, --smarten-punctuation, --remove-unused-css, --add-soft-hyphens, --remove-soft-hyphens, --upgrade-book, --download-external-resources, --verbose

`library` -- Library Management

Command	Description
`library list`	List all configured libraries
`library info`	Get library statistics (book count)
`library check`	Check library consistency
`library backup`	Backup metadata to OPF files
`library catalog OUTPUT`	Generate a calibre catalog
`library custom-column list/add/remove`	Manage custom columns
`library clone DESTINATION`	Clone library structure/settings
`library restore-database --apply`	Restore metadata.db from OPF files
`library remote-list URL`	List Content Server library IDs

`tag` -- Tag Operations

Command	Description
`tag list`	List all tags and categories
`tag search QUERY`	Search books by tag

tag list options: --categories

`fts` -- Full-Text Search

Command	Description
`fts enable`	Enable full-text search indexing
`fts disable`	Disable full-text search indexing
`fts status`	Check FTS index status
`fts search QUERY`	Search across book contents

fts search options: --include-snippets / --no-snippets

`config` -- Configuration

Command	Description
`config show`	Show current configuration
`config set KEY VALUE`	Set a configuration value
`config add-library NAME PATH`	Register a library by name

`device` -- Device Operations

Command	Description
`device detect`	Detect connected devices
`device list`	List connected devices
`device books`	List books on a device
`device storage`	Show device storage information
`device info`	Show device information
`device send BOOK_ID`	Send a library book to a device
`device remove DEVICE_BOOK_ID --yes`	Remove a book from a device
`device eject`	Eject the connected device

`server` -- Content Server

Command	Description
`server status URL`	Check a calibre Content Server URL
`server start --library PATH`	Start `calibre-server` for a library
`server stop --pid-file FILE`	Stop a server process owned by that pid file

`plugin` and `debug`

Command	Description
`plugin list`	List installed calibre plugins
`plugin install PATH`	Install a calibre plugin
`plugin remove NAME --yes`	Remove a calibre plugin
`debug diagnostics`	Return selected `calibre-debug` diagnostics

Multi-Library Configuration

calibre-cli stores its configuration at:

~/.config/calibre-cli/config.json

Example configuration:

{
  "default_library": "main",
  "libraries": {
    "main": "/Users/me/Calibre Library",
    "technical": "/Users/me/Technical Books",
    "fiction": "/Users/me/Fiction"
  },
  "calibre_paths": {
    "calibredb": "calibredb",
    "ebook_convert": "ebook-convert",
    "ebook_meta": "ebook-meta",
    "fetch_ebook_metadata": "fetch-ebook-metadata",
    "ebook_polish": "ebook-polish",
    "calibre_device": "calibre-device",
    "calibre_server": "calibre-server",
    "calibre_debug": "calibre-debug",
    "calibre_customize": "calibre-customize"
  },
  "defaults": {
    "list_limit": 50,
    "output_format": "json",
    "subprocess_timeout": 300
  }
}

Use named libraries with any command:

calibre-cli --library technical book list
calibre-cli --library fiction book search "author:Asimov"

The first library added via config add-library automatically becomes the default.

Error Handling

All errors are returned as JSON with a machine-readable error code, a human-readable message, and an optional details object. The process exits with a non-zero code.

{
  "success": false,
  "error": {
    "code": "BOOK_NOT_FOUND",
    "message": "Book 999 not found",
    "details": {}
  }
}

Error Codes

Code	Exit Code	Description
`UNKNOWN_ERROR`	1	Unexpected failure
`CALIBRE_NOT_FOUND`	3	calibre CLI tools not found on PATH
`LIBRARY_NOT_FOUND`	4	Specified library path does not exist
`LIBRARY_LOCKED`	4	Library is locked by another process
`INVALID_ARGUMENT`	2	Invalid argument or option value
`BOOK_NOT_FOUND`	1	Book ID does not exist in the library
`BOOK_DUPLICATE`	1	Book already exists (and duplicates not allowed)
`FILE_NOT_FOUND`	1	Specified file path does not exist
`FORMAT_NOT_FOUND`	1	Requested format not available for the book
`FORMAT_NOT_SUPPORTED`	1	Format not supported by calibre
`CONVERSION_FAILED`	1	ebook-convert returned an error
`METADATA_FETCH_FAILED`	1	Online metadata fetch returned no results
`FIELD_NOT_FOUND`	2	Metadata field name not recognized
`CONFIRMATION_REQUIRED`	2	A destructive command requires `--yes` or `--apply`
`REMOTE_UNSUPPORTED`	2	Command is not supported for remote Content Server libraries
`DEVICE_ERROR`	1	Device command failed
`SERVER_ERROR`	1	Server command failed
`DEBUG_ERROR`	1	Debug command failed
`PLUGIN_ERROR`	1	Plugin command failed

For Automation

calibre-cli is designed for programmatic consumption. When integrating:

Parse stdout as JSON. Every command writes a single JSON object to stdout. Errors are written to stderr and also formatted as JSON.
Check success first. If success is false, read error.code for the machine-readable reason.
Use --library to target a specific library, or configure a default with config add-library.
Paginate with --limit and --offset when listing books. The meta object in the response contains total, offset, and limit.
Pipe JSON into batch operations. Commands like metadata batch-set accept JSON via --from-json - (stdin).

Example automation workflow:

# 1. Verify calibre is available
calibre-cli doctor

# 2. Register the library
calibre-cli config add-library main /path/to/library

# 3. Search for books
calibre-cli book search "author:Knuth" --limit 10

# 4. Update metadata from JSON
echo '{"book_ids": [1, 2, 3], "fields": {"tags": "computer-science,algorithms"}}' \
  | calibre-cli metadata batch-set --from-json -

# 5. Convert a book
calibre-cli format convert /path/to/book.epub --to pdf

Development

Running Tests

See Development for local setup, the current pytest defaults for unit tests, and optional real-calibre integration test commands.

Continuous Integration

CI runs unit tests on Python 3.10-3.13 and builds the package. Integration tests require calibre, are marked integration, and are excluded from default CI.

Project Structure

calibre-cli/
├── pyproject.toml
├── src/calibre_cli/
│   ├── cli.py                  # Click root group + doctor command
│   ├── errors.py               # ErrorCode enum + CalibreCliError
│   ├── output.py               # success_response() / error_response()
│   ├── config.py               # Config dataclass, load/save/resolve
│   ├── runners/                # Subprocess wrappers
│   │   ├── base.py             # BaseRunner
│   │   ├── calibredb.py        # CalibreDBRunner
│   │   ├── convert.py          # ConvertRunner (ebook-convert)
│   │   ├── meta.py             # MetaRunner (ebook-meta)
│   │   ├── fetch.py            # FetchRunner (fetch-ebook-metadata)
│   │   ├── polish.py           # PolishRunner (ebook-polish)
│   │   ├── device.py           # DeviceRunner
│   │   ├── server.py           # ServerRunner (calibre-server)
│   │   ├── debug.py            # DebugRunner (calibre-debug)
│   │   └── plugin.py           # PluginRunner (calibre-customize)
│   ├── parsers/                # Output parsers
│   │   ├── opf.py              # OPF XML parser
│   │   ├── text.py             # Free-text output parser
│   │   └── csv_parser.py       # CSV output parser
│   └── commands/               # Click command groups
│       ├── book.py
│       ├── metadata.py
│       ├── format_.py
│       ├── library.py
│       ├── device.py
│       ├── server.py
│       ├── debug.py
│       ├── plugin.py
│       ├── tag.py
│       ├── fts.py
│       └── config_cmd.py
└── tests/

Architecture

Automation (shell) --> calibre-cli CLI (Python/Click) --> subprocess --> calibre CLI tools --> local library

The wrapper never imports calibre's Python modules. All interaction goes through subprocess calls to calibre's CLI tools, parsing their text/XML/JSON output into a unified JSON response format.

License

MIT

Name		Name	Last commit message	Last commit date
docs		docs
src/calibre_cli		src/calibre_cli
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

calibre-cli

Status

Features

Prerequisites

Installation

Development Setup

Quick Start

Check your environment

Register a library

List books

Get book details

Add a book

Update metadata

Convert format

Command Reference

Global Options

doctor

book -- Book Management

metadata -- Metadata Operations

format -- Format Management

library -- Library Management

tag -- Tag Operations

fts -- Full-Text Search

config -- Configuration

device -- Device Operations

server -- Content Server

plugin and debug