# Readwise Docs

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

- Skill: `edwinhu/readwise-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add edwinhu/readwise-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/edwinhu/readwise-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: edwinhu (https://skillmd.com/u/edwinhu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/edwinhu/readwise-docs

---


# Readwise Reader Document Management

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