Back to Details

cli-anything-calibre

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cli-anything-calibre

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.
一个用于Calibre电子书管理的有状态CLI封装工具。它基于真实的Calibre工具（
calibredb
、
ebook-convert
、
ebook-meta
）构建，为AI Agent和脚本提供简洁、结构化的接口，用于库操作、元数据编辑和格式转换。

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
undefined
该CLI作为cli-anything-calibre包的一部分进行安装：
bash
pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness
前置要求：
  • Python 3.10+
  • 系统必须已安装Calibre（硬性依赖）
bash
undefined

Debian/Ubuntu

Debian/Ubuntu

sudo apt-get install calibre
sudo apt-get install calibre

macOS

macOS

brew install --cask calibre
brew install --cask calibre

Verify tools are in PATH

验证工具是否在PATH中

which calibredb which ebook-convert which ebook-meta
undefined
which calibredb which ebook-convert which ebook-meta
undefined

Usage

使用方法

Basic Commands

基础命令

bash
undefined
bash
undefined

Show help

显示帮助信息

cli-anything-calibre --help
cli-anything-calibre --help

Start interactive REPL mode

启动交互式REPL模式

cli-anything-calibre
cli-anything-calibre

Connect to a Calibre library

连接到Calibre库

cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre library connect ~/Calibre\ Library

Run with JSON output (for agent consumption)

以JSON格式输出（供Agent使用）

cli-anything-calibre --json books list
undefined
cli-anything-calibre --json books list
undefined

REPL Mode

REPL模式

When invoked without a subcommand, the CLI enters an interactive REPL session:
bash
cli-anything-calibre
当不指定子命令调用时，CLI会进入交互式REPL会话：
bash
cli-anything-calibre

Enter commands interactively with tab-completion and history

交互式输入命令，支持自动补全和历史记录

Use 'help' to see available commands

使用'help'查看可用命令

Use 'quit' or 'exit' to leave

使用'quit'或'exit'退出

undefined
undefined

Command Groups

命令组

Library

库管理

Library management commands.
CommandDescription
connect <path>
Set active library path
info
Show library statistics (book count, formats, db size)
check
Verify library integrity using calibredb check_library
库管理命令。
命令描述
connect <path>
设置当前激活的库路径
info
显示库统计信息（书籍数量、格式、数据库大小）
check
使用calibredb check_library验证库完整性

Books

书籍操作

Book operations (wrap 
calibredb
).
CommandDescription
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)
书籍操作命令（封装
calibredb
）。
命令描述
list
列出书籍，支持筛选和排序
search <query>
使用Calibre查询语言搜索
add <files>
将书籍文件添加到库中
remove <ids>
删除书籍（移至回收站或永久删除）
show <id>
显示书籍的完整元数据
export <ids>
将书籍导出到指定目录
export-chapters <id>
将每一章导出为单独的PDF文件（需要EPUB格式）

Meta

元数据编辑

Metadata editing (wrap 
calibredb set_metadata
).
CommandDescription
get <id> [field]
Get metadata (all or specific field)
set <id> <field> <value>
Set a metadata field
embed <ids>
Embed metadata into book files
元数据编辑命令（封装
calibredb set_metadata
）。
命令描述
get <id> [field]
获取元数据（全部或指定字段）
set <id> <field> <value>
设置元数据字段
embed <ids>
将元数据嵌入书籍文件

Formats

格式管理

Format management (wrap 
calibredb
+ 
ebook-convert
).
CommandDescription
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
格式管理命令（封装
calibredb
+ 
ebook-convert
）。
命令描述
list <id>
列出书籍的可用格式
add <id> <file>
为书籍添加一种格式
remove <id> <fmt>
删除书籍的指定格式
convert <id> <input_fmt> <output_fmt>
转换书籍格式

Custom

自定义列

Custom columns (wrap 
calibredb
).
CommandDescription
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
自定义列命令（封装
calibredb
）。
命令描述
list
列出所有自定义列
add <label> <name> <type>
创建自定义列
remove <label>
删除自定义列
set <id> <label> <value>
设置自定义字段值

Catalog

目录生成

Catalog generation.
CommandDescription
catalog <output>
Generate a catalog of the library (EPUB, CSV, or OPDS)
目录生成命令。
命令描述
catalog <output>
生成库的目录（EPUB、CSV或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
连接到你的Calibre库并列出书籍。
bash
cli-anything-calibre library connect ~/Calibre\ Library
cli-anything-calibre books list

Or with JSON output

或以JSON格式输出

cli-anything-calibre --json books list --search "author:asimov"
undefined
cli-anything-calibre --json books list --search "author:asimov"
undefined

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"
使用Calibre查询语言搜索书籍。
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
设置书籍的元数据字段。
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
在电子书格式之间转换。
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

将章节导出为PDF

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
将EPUB的每一章导出为单独的PDF文件。
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

Calibre查询语言

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
用于
books search
和
books list --search
命令：
author:asimov                    # 作者包含"asimov"
title:"Foundation"               # 精确匹配书名短语
tags:fiction                     # 标签匹配
rating:>3                        # 评分大于3
series:"Foundation"              # 系列匹配
pubdate:[2020-01-01,2021-12-31]  # 日期范围
identifiers:isbn:1234567890      # 特定标识符
has:cover                        # 包含封面图片
not:tags:fiction                 # 取反
author:asimov and tags:scifi     # 布尔逻辑AND

Key Metadata Fields

关键元数据字段

FieldTypeDescription
title
textBook title
authors
textAuthor names (&-separated)
tags
textComma-separated tags
series
textSeries name
series_index
floatPosition in series
rating
floatRating 1-5
publisher
textPublisher name
pubdate
datetimePublication date
comments
textDescription/comments
languages
textLanguage codes
identifiers
textISBN, ASIN, etc. (
type:value
)
字段类型描述
title
文本书籍标题
authors
文本作者姓名（用&分隔）
tags
文本逗号分隔的标签
series
文本系列名称
series_index
浮点数在系列中的位置
rating
浮点数评分1-5
publisher
文本出版社名称
pubdate
日期时间出版日期
comments
文本描述/评论
languages
文本语言代码
identifiers
文本ISBN、ASIN等（格式为
类型:值
）

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
输入格式： EPUB、MOBI、AZW、AZW3、PDF、HTML、DOCX、ODT、FB2、TXT、RTF、LIT等
输出格式（转换）： EPUB、MOBI、AZW3、PDF、HTML、DOCX、TXT等

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
CLI通过以下方式维护会话状态：
  • 会话文件：
    ~/.cli-anything-calibre/session.json
  • 库路径持久化：激活的库路径会在会话间保存
  • 环境变量覆盖：
    CALIBRE_LIBRARY
    环境变量

Output Formats

输出格式

All commands support dual output modes:
  • Human-readable (default): Tables, colors, formatted text
  • Machine-readable (
    --json
    flag): Structured JSON for agent consumption
bash
undefined
所有命令支持两种输出模式：
  • 人类可读格式（默认）：表格、颜色、格式化文本
  • 机器可读格式（
    --json
    标志）：结构化JSON，供Agent使用
bash
undefined

Human output

人类可读输出

cli-anything-calibre books list
cli-anything-calibre books list

JSON output for agents

供Agent使用的JSON输出

cli-anything-calibre --json books list
undefined
cli-anything-calibre --json books list
undefined

For AI Agents

针对AI Agent的使用说明

When using this CLI programmatically:
  1. Always use 
    --json
    flag     for parseable output
  2. Check return codes - 0 for success, non-zero for errors
  3. Parse stderr for error messages on failure
  4. Verify outputs exist after export/conversion operations
  5. Use 
    --library
    flag     or 
    CALIBRE_LIBRARY
    env to specify library path
  6. Chapter export requires EPUB format - convert first if needed
以编程方式使用该CLI时：
  1. 始终使用
    --json
    标志    以获得可解析的输出
  2. 检查返回码 - 0表示成功，非0表示错误
  3. 解析stderr以获取失败时的错误信息
  4. 验证输出是否存在在导出/转换操作后
  5. 使用
    --library
    标志    或
    CALIBRE_LIBRARY
    环境变量指定库路径
  6. 章节导出需要EPUB格式 - 必要时先进行转换

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
  • 完整文档：查看包中的README.md
  • 架构标准操作流程：查看agent-harness目录中的CALIBRE.md
  • 测试覆盖率：查看tests目录中的test_core.py和test_full_e2e.py
  • 方法论：查看cli-anything-plugin中的HARNESS.md

Version

版本

1.0.0
1.0.0