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

# 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

# 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

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