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

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:

Search Documents (Hybrid)

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

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

Save URL

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

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

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

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

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

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)

readwise-custom delete <id>

Highlights & Books (v2 API)

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)

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

Piping & Scripting

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

# 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