cli-anything-calibre

cli-anything-calibre

Calibre 電子書籍管理のためのステートフルな CLI ハーネスです。実際の Calibre ツール（calibredb、ebook-convert、ebook-meta）をラップし、AI エージェントやスクリプトに、ライブラリ操作、メタデータ編集、フォーマット変換のためのクリーンで構造化されたインターフェースを提供します。

インストール

この CLI は cli-anything-calibre パッケージの一部としてインストールされます:

pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=calibre/agent-harness

前提条件:

• Python 3.10 以上
• Calibre がシステムにインストールされている必要があります（必須依存）

# 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

使用方法

基本コマンド

# 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 モード

サブコマンドなしで起動すると、CLI は対話型 REPL セッションに入ります:

cli-anything-calibre
# Enter commands interactively with tab-completion and history
# Use 'help' to see available commands
# Use 'quit' or 'exit' to leave

コマンドグループ

Library

ライブラリ管理コマンド。

コマンド	説明
connect <path>	アクティブなライブラリパスを設定
info	ライブラリの統計情報（書籍数、フォーマット、DB サイズ）を表示
check	calibredb check_library を使用してライブラリの整合性を検証

Books

書籍操作（calibredb をラップ）。

コマンド	説明
list	フィルタリングと並べ替えを行って書籍を一覧表示
search <query>	Calibre クエリ言語を使用して検索
add <files>	書籍ファイルをライブラリに追加
remove <ids>	書籍を削除（ゴミ箱に移動、または完全削除）
show <id>	書籍の完全なメタデータを表示
export <ids>	書籍をディレクトリにエクスポート
export-chapters <id>	各章を個別の PDF としてエクスポート（EPUB 形式が必要）

Meta

メタデータ編集（calibredb set_metadata をラップ）。

コマンド	説明
get <id> [field]	メタデータを取得（すべて、または特定のフィールド）
set <id> <field> <value>	メタデータフィールドを設定
embed <ids>	メタデータを書籍ファイルに埋め込み

Formats

フォーマット管理（calibredb + ebook-convert をラップ）。

コマンド	説明
list <id>	書籍で利用可能なフォーマットを一覧表示
add <id> <file>	書籍にフォーマットを追加
remove <id> <fmt>	書籍からフォーマットを削除
convert <id> <input_fmt> <output_fmt>	書籍のフォーマットを変換

Custom

カスタム列（calibredb をラップ）。

コマンド	説明
list	すべてのカスタム列を一覧表示
add <label> <name> <type>	カスタム列を作成
remove <label>	カスタム列を削除
set <id> <label> <value>	カスタムフィールドの値を設定

Catalog

カタログ生成。

コマンド	説明
catalog <output>	ライブラリのカタログを生成（EPUB、CSV、または OPDS）

例

接続して書籍を一覧表示

Calibre ライブラリに接続し、書籍を一覧表示します。

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"

検索とフィルタリング

Calibre クエリ言語を使用して書籍を検索します。

cli-anything-calibre books search "title:Foundation"
cli-anything-calibre books search "author:asimov and tags:scifi"
cli-anything-calibre books search "rating:>3"

メタデータ編集

書籍のメタデータフィールドを設定します。

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

フォーマット変換

電子書籍フォーマット間で変換します。

cli-anything-calibre formats convert 42 EPUB MOBI
cli-anything-calibre formats convert 42 EPUB PDF --output /tmp/book.pdf

章を PDF としてエクスポート

EPUB の各章を個別の PDF ファイルとしてエクスポートします。

cli-anything-calibre books export-chapters 42 --to-dir ./pdfs
cli-anything-calibre books export-chapters 42 --to-dir ./pdfs --chapters 1-5

Calibre クエリ言語

books search および 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

主要なメタデータフィールド

フィールド	型	説明
title	text	書籍のタイトル
authors	text	著者名（& 区切り）
tags	text	カンマ区切りのタグ
series	text	シリーズ名
series_index	float	シリーズ内の位置
rating	float	評価 1〜5
publisher	text	出版社名
pubdate	datetime	出版日
comments	text	説明/コメント
languages	text	言語コード
identifiers	text	ISBN、ASIN など（type:value）

対応フォーマット

入力: EPUB、MOBI、AZW、AZW3、PDF、HTML、DOCX、ODT、FB2、TXT、RTF、LIT など

出力（変換）: EPUB、MOBI、AZW3、PDF、HTML、DOCX、TXT など

状態管理

CLI は以下でセッション状態を維持します。

• セッションファイル: ~/.cli-anything-calibre/session.json
• ライブラリパスの永続化: アクティブなライブラリはセッションをまたいで保存されます
• 環境変数によるオーバーライド: CALIBRE_LIBRARY 環境変数

出力形式

すべてのコマンドは 2 つの出力モードをサポートしています。

• 人間が読みやすい形式（デフォルト）: テーブル、色、整形されたテキスト
• 機械可読形式（--json フラグ）: エージェントが利用するための構造化 JSON

# Human output
cli-anything-calibre books list

# JSON output for agents
cli-anything-calibre --json books list

AI エージェント向け

この CLI をプログラムから使用する場合:

1. 常に --json フラグを使用してください — 解析可能な出力を得るため
2. リターンコードを確認してください — 0 は成功、非ゼロはエラー
3. stderr を解析してください — 失敗時のエラーメッセージを取得するため
4. 出力が存在することを確認してください — エクスポート/変換操作の後
5. --library フラグまたは CALIBRE_LIBRARY 環境変数を使用してライブラリパスを指定してください
6. 章のエクスポートには EPUB 形式が必要です — 必要に応じて先に変換してください

詳細情報

• 完全なドキュメント: パッケージ内の README.md を参照してください
• アーキテクチャ SOP: agent-harness ディレクトリ内の CALIBRE.md を参照してください
• テストカバレッジ: tests ディレクトリ内の test_core.py および test_full_e2e.py を参照してください
• 方法論: cli-anything-plugin 内の HARNESS.md を参照してください

バージョン

1.0.0