Readwise Search

---
name: readwise-search
description: ALWAYS use when the user wants something out of their own reading library — "what did I highlight about X", "search my highlights", "find in readwise", "my notes on X", "did I save anything on Y", "what have I read about Z", "find that quote I saved", "pull quotes from my reading", "who was it that said X". Use proactively before answering from memory whenever the user refers to their own reading or annotations. NOT for conversational summarizing across highlights (readwise-chat), listing or saving Reader documents (readwise-docs), or cleanup (readwise-prune).
context: fork
agent: librarian
user-invocable: false
---

# Readwise Highlight Search

**What this skill carries** — grep `references/` for any subject the names below miss:
!`d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"`

## Decision Tree

```
1. Do you know the EXACT document or author?
   YES -> Use fulltext filters (--full-text-queries)
   NO  -> Use vector search (semantic query)
2. Need document-level results (not highlights)?
   YES -> Use `readwise reader-search-documents --query "term"`
          or `readwise reader-list-documents` with --tag or --category filters
   NO  -> Use `readwise readwise-search-highlights`
3. Need keyword-exact match in highlight text?
   YES -> Use `readwise-custom highlights --search "term"` (v2 API)
   NO  -> Use vector search
```

## Quick Reference

### Vector + Fulltext Search (Highlights) — Official CLI

```bash
# Semantic search
readwise readwise-search-highlights --vector-search-term "fiduciary duty broker-dealer"

# With fulltext filters
readwise readwise-search-highlights --vector-search-term "regulation" \
  --full-text-queries '[{"field_name": "document_author", "search_term": "Jackson"}]'

# JSON output for piping
readwise readwise-search-highlights --vector-search-term "query" --json
```

**Fulltext filter fields** (via `--full-text-queries` JSON array):

| field_name | Searches |
|------------|----------|
| `document_author` | Document author name |
| `document_title` | Document title |
| `highlight_note` | Highlight notes/annotations |
| `highlight_plaintext` | Highlight text content |
| `highlight_tags` | Tags on highlights |

### Document Search (Hybrid) — Official CLI

```bash
# Hybrid search across document content
readwise reader-search-documents --query "proxy advisors"

# With filters
readwise reader-search-documents --query "regulation" --author-search "Jackson" --category-in article
readwise reader-search-documents --query "proxy" --tags-in "corps" --location-in later,archive

# By tag (no search, just filter)
readwise reader-list-documents --tag "proxy advisors" --json

# By category and location
readwise reader-list-documents --category article --location archive

# Recent updates
readwise reader-list-documents --updated-after 2026-01-01T00:00:00Z --limit 20
```

### Keyword Highlight Search — Custom CLI

```bash
# Exact text search across highlights (v2 API)
readwise-custom highlights --search "fiduciary" --limit 20 --json
```

## When to Use Each

| Need | Command | CLI |
|------|---------|-----|
| Semantic/conceptual highlight search | `readwise readwise-search-highlights --vector-search-term "query"` | Official |
| Hybrid document content search | `readwise reader-search-documents --query "term"` | Official |
| Keyword-exact match in highlights | `readwise-custom highlights --search "term"` | Custom |
| Documents by tag | `readwise reader-list-documents --tag "X"` | Official |
| Specific document | `readwise reader-get-document-details --document-id <id>` | Official |

## Output Format

Use `--json` for structured output. JSON search results include a `score` field (higher = more relevant, >0.01 typically meaningful).