Readwise Docs

---
name: readwise-docs
description: "Use when the user says 'add to reader', 'save this article', 'read this later', 'put this in Readwise', 'list my documents', 'what's in my reading inbox', 'archive that article', 'tag this document', or 'delete that from Reader' - anything that lists, saves, updates or deletes documents in the Readwise Reader library. NOT for searching highlights (readwise-search) and NOT for bulk cleanup of stale documents (readwise-prune)."
context: fork
agent: librarian
user-invocable: false
---

# Readwise Reader Document Management

**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)"`

CRUD operations on the Reader document library via official CLI (`readwise`) and custom CLI (`readwise-custom`).

## Commands — Official CLI (`readwise`)

### List Documents

```bash
readwise reader-list-documents                                    # All documents (limit 10)
readwise reader-list-documents --limit 20                         # First 20
readwise reader-list-documents --tag "proxy advisors"             # By tag (up to 5 for AND logic)
readwise reader-list-documents --category pdf --location archive  # By category + location
readwise reader-list-documents --updated-after 2026-01-01T00:00:00Z
readwise reader-list-documents --seen false                       # Unseen only
readwise reader-list-documents --response-fields title,author,summary  # Reduce token usage
readwise reader-list-documents --id <id>                          # Specific document
```

**Filter values:**

| Flag | Values |
|------|--------|
| `--location` | `new` (inbox), `later`, `shortlist`, `archive`, `feed` |
| `--category` | `article`, `email`, `rss`, `highlight`, `note`, `pdf`, `epub`, `tweet`, `video`, `podcast`, `audiobook` |
| `--tag` | Any tag name (up to 5 tags for AND logic) |
| `--seen` | `true` (opened), `false` (unopened) |

### Search Documents (Hybrid)

```bash
readwise reader-search-documents --query "proxy advisors"
readwise reader-search-documents --query "regulation" --author-search "Jackson"
readwise reader-search-documents --query "AI" --category-in article --location-in later,archive
readwise reader-search-documents --query "climate" --published-date-gt 2025-01-01
```

### Get Document

```bash
readwise reader-get-document-details --document-id <id>   # Returns markdown content
```

### Save URL

```bash
readwise reader-create-document --url https://example.com/article
readwise reader-create-document --url https://example.com --title "Title" --tags research,ai --notes "Note"
readwise reader-create-document --title "Custom Doc" --markdown "# Content..." --url "https://me.com#doc1"
```

### Move Documents

```bash
readwise reader-move-documents --document-ids <id1>,<id2> --location archive   # Max 50 per call
readwise reader-move-documents --document-ids <id> --location later
```

### Bulk Edit Metadata

```bash
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "seen": true}]'
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "title": "New Title"}]'
```

### Tags

```bash
readwise reader-list-tags                                                    # List all tags
readwise reader-add-tags-to-document --document-id <id> --tag-names important,research
readwise reader-remove-tags-from-document --document-id <id> --tag-names old-tag
```

### Highlights

```bash
readwise reader-get-document-highlights --document-id <id>
readwise reader-create-highlight --document-id <id> --html-content "<p>passage</p>"
readwise reader-create-highlight --document-id <id> --html-content "<p>passage</p>" --note "Note" --tags concept
readwise reader-add-tags-to-highlight --document-id <id> --highlight-document-id <hid> --tag-names concept
readwise reader-set-highlight-notes --document-id <id> --highlight-document-id <hid> --notes "Updated note"
```

### Export

```bash
readwise reader-export-documents                                         # Full library as ZIP of markdown
readwise reader-export-documents --since-updated "2026-01-01T00:00:00Z"  # Delta export
readwise reader-get-export-documents-status --export-id <id>             # Check status
```

## Commands — Custom CLI (`readwise-custom`)

### Delete Document (not available in official CLI)

```bash
readwise-custom delete <id>
```

### Highlights & Books (v2 API)

```bash
readwise-custom highlights                              # All highlights
readwise-custom highlights --search "fiduciary"         # Keyword search
readwise-custom highlights --book-id 12345 --json       # By source

readwise-custom books                                   # All sources
readwise-custom books --category articles --search "law"
```

### Upload File (PDF/EPUB)

```bash
readwise-custom upload <file.pdf>
readwise-custom upload <file.epub>
```

## Piping & Scripting

All commands support `--json` for machine-readable output:

```bash
# Get IDs of all PDFs
readwise reader-list-documents --category pdf --json | jq -r '.results[].id'

# Count highlights per book
readwise-custom books --json | jq '.[] | {title, num_highlights}'

# Export all tags
readwise reader-list-tags --json > tags.json
```