📘 Khy-OS 文档站 🧭 新手先读：核心概念

# cli-anything-calibre

name: "cli-anything-calibre"
description: >-
Command-line interface for Calibre - A stateful CLI harness for e-book library management, metadata editing, and format conversion wrapping the real Calibre tools (calibredb, ebook-convert, ebook-meta)...

# 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)

### Meta#

Metadata editing (wrap `calibredb set_metadata`).

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:

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

## 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