---
name: calibre
description: Search and query Calibre library databases. Use when the user asks about books, TBR (to-be-read), reading lists, Calibre library queries, book searches, or mentions Calibre. Also use for queries about book ratings, authors, reading status, or library statistics.
---

# Calibre Library Search Skill

You are helping the user search and query their Calibre library using `calibredb`.

## Library Setup

**Library URL**: `http://killington.home.bitbin.de:8454/#`

**calibredb Location**: `/Applications/calibre.app/Contents/MacOS/calibredb`

**Authentication**:
- Username: `calibre`
- Password: `calibre`

**Note**: Using Calibre Content Server means no database locking issues - queries work even while Calibre GUI is running.

## Custom Fields

The Calibre library has these custom fields:

| Field      | Search Name | Display Name | Type     | Values       |
|------------|-------------|--------------|----------|--------------|
| read       | #read       | *read        | Boolean  | Yes/No       |
| dateread   | #dateread   | *dateread    | Datetime | ISO date     |
| archived   | #archived   | *archived    | Boolean  | Yes/No       |
| goodreads  | #goodreads  | *goodreads   | Float    | 0.0-5.0      |
| pages      | #pages      | *pages       | Integer  | page count   |
| priority   | #priority   | *priority    | Text     | varies       |
| words      | #words      | *words       | Integer  | word count   |

**IMPORTANT - Boolean Field Syntax**:
- Use `#field` syntax in searches with `Yes` or `No` (capitalized): e.g., `#read:Yes`, `#read:No`
- Use `*field` syntax when displaying fields (e.g., `*read`)
- Boolean values are **NOT** `true`/`false` - they are `Yes`/`No`

## calibredb Command Pattern

Always use this pattern:

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='field1,field2,*customfield' \
  --search='search query' \
  --for-machine | python3 -m json.tool
```

### Common Options

- `--fields='field1,field2'` - Comma-separated list of fields to display
- `--search='query'` - Search query using Calibre's search syntax
- `--sort-by='field'` - Sort results by field
- `--limit=N` - Limit results to N books
- `--for-machine` - Output as JSON (always use this for parsing)

### Available Built-in Fields

- `title`, `authors`, `series`, `series_index`
- `timestamp` (when added to library)
- `last_modified` (when book record was last modified)
- `pubdate`, `publisher`, `isbn`
- `rating`, `tags`, `comments`
- `formats`, `size`, `uuid`

## Search Query Syntax

### Basic Searches

```bash
# Search by title
--search='title:"Book Title"'

# Search by author
--search='authors:"Author Name"'

# Search in series
--search='series:"Series Name"'

# Combine searches with AND
--search='authors:"Sanderson" and series:"Mistborn"'

# Combine searches with OR
--search='authors:"Sanderson" or authors:"Wells"'

# NOT operator
--search='not #archived:Yes'
```

### Custom Field Searches

```bash
# Books marked as read
--search='#read:Yes'

# Books NOT read
--search='#read:No'

# Books not archived and not read (TBR)
--search='#read:No and #archived:No'

# Highly rated books (>= 4.0)
--search='#goodreads:">4"'

# Books with specific page count
--search='#pages:"<300"'

# Empty/not set custom fields
--search='#goodreads:""'

# Books read in a specific date range
--search='#dateread:">=2024-01-01" and #dateread:"<2025-01-01"'

# Books read in the last 30 days
--search='#dateread:">=30daysago"'
```

## Common Query Examples

### To-Be-Read List

Get unread, non-archived books:

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,series,series_index,*goodreads,*pages' \
  --search='#read:No and #archived:No' \
  --for-machine | python3 -m json.tool
```

### Recently Added Books

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,*goodreads,*pages,timestamp' \
  --search='#read:No and #archived:No' \
  --sort-by='timestamp' \
  --limit=10 \
  --for-machine | python3 -m json.tool
```

### Recently Read Books

Use the `*dateread` field to see when books were actually finished:

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,series,series_index,*goodreads,*pages,*dateread' \
  --search='#read:Yes' \
  --sort-by='*dateread' \
  --limit=15 \
  --for-machine | python3 -m json.tool
```

### Highly Rated Unread Books

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,series,*goodreads,*pages' \
  --search='#read:No and #archived:No and #goodreads:">4"' \
  --sort-by='*goodreads' \
  --for-machine | python3 -m json.tool
```

### Books by Specific Author

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,series,*read,*goodreads,*pages' \
  --search='authors:"Sanderson" and #archived:No' \
  --for-machine | python3 -m json.tool
```

### Quick Reads (< 300 pages)

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,*pages,*goodreads' \
  --search='#read:No and #archived:No and #pages:"<300"' \
  --sort-by='*goodreads' \
  --for-machine | python3 -m json.tool
```

### Unread Books in a Series

```bash
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,series,series_index,*goodreads,*pages,timestamp' \
  --search='series:"Between Earth and Sky" and #read:No and #archived:No' \
  --sort-by='series_index' \
  --for-machine | python3 -m json.tool
```

### Books Read in a Time Period

```bash
# Books read in October 2024
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,*dateread,*goodreads,*pages' \
  --search='#dateread:">=2024-10-01" and #dateread:"<2024-11-01"' \
  --sort-by='*dateread' \
  --for-machine | python3 -m json.tool

# Books read this year
/Applications/calibre.app/Contents/MacOS/calibredb list \
  --with-library='http://killington.home.bitbin.de:8454/#' \
  --username='calibre' \
  --password='calibre' \
  --fields='title,authors,*dateread,*goodreads' \
  --search='#dateread:">=2025-01-01"' \
  --sort-by='*dateread' \
  --for-machine | python3 -m json.tool
```

## Usage Instructions

When the user asks to search their Calibre library:

1. **Determine** what they're looking for (to-be-read, specific book, by rating, etc.)
2. **Construct** the appropriate calibredb command based on examples above
3. **Execute** the command using the Bash tool
4. **Parse** the JSON output and present results in a readable format

## Query Tips

- **Always exclude archived books** unless specifically requested: add `and #archived:No` to searches
- Use `--for-machine` to get JSON output that's easier to parse
- The `timestamp` field shows when a book was added to the library
- The `*dateread` field shows when a book was actually finished reading (synced from Goodreads)
- The `last_modified` field shows when a book record was last changed (not reliable for "recently read")
- When a custom field is not set, it won't appear in the JSON output
- Use `python3 -m json.tool` to pretty-print JSON for readability
- Search queries are case-insensitive
- Use quotes around field values that contain spaces
- **Boolean fields**: In search queries use `Yes`/`No` (e.g., `#read:Yes`), but in JSON output they appear as `true`/`false` (lowercase)
- **Date fields**: Use `*dateread` to sort by when books were actually read (more accurate than `last_modified`)

## Examples

**User**: "Show me my to-be-read list"
→ Search with `#read:No and #archived:No`

**User**: "Find books by Sanderson"
→ Search with `authors:"Sanderson" and #archived:No`

**User**: "Show highly rated unread books"
→ Search with `#read:No and #archived:No and #goodreads:">4"`

**User**: "What did I read recently?"
→ Search with `#read:Yes`, sort by `*dateread` (descending), limit to 10-15

**User**: "What's next in the series I'm reading?"
→ Find series from recent reads, then search for unread books in that series

**User**: "What did I read in October?" or "Show me books I read this year"
→ Use date range searches with `#dateread:">=2024-10-01" and #dateread:"<2024-11-01"` or `#dateread:">=2025-01-01"`

## Safety Notes

- **Read-only access**: calibredb list is a read-only operation
- **Never use**: `calibredb add`, `calibredb set_metadata`, `calibredb remove` unless explicitly requested by user
- **No locking issues**: Using the Content Server means the Calibre GUI can remain open during queries