calibre

What this skill does

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