readwiseio Readwise CLI
Use the readwise command to access the user's Readwise highlights and Reader documents. Readwise has two products:
- Readwise — highlights from books, articles, podcasts, and more. Includes daily review and spaced repetition.
- Reader — a read-later app for saving and reading articles, PDFs, EPUBs, RSS feeds, emails, tweets, and videos.
Setup
If readwise is not installed:
npm install -g @readwise/cli
If not authenticated, ask the user for their Readwise access token (they can get one at https://readwise.io/access_token), then run:
readwise login-with-token <token>
Discovering Commands
Every command supports --help for full option details:
readwise --help
readwise reader-search-documents --help
readwise readwise-list-highlights --help
Add --json to any command for machine-readable output. Use --refresh to force-refresh cached data.
Reader Commands
Searching and browsing documents
# Semantic search across all saved documents
readwise reader-search-documents --query "spaced repetition"
# Search with filters — by category, location, author, date range, tags
readwise reader-search-documents --query "machine learning" --category-in article --location-in later,shortlist
# List recent inbox items with minimal fields (saves tokens)
readwise reader-list-documents --location new --limit 10 --response-fields title,author,summary,word_count,category
# List archived articles by a specific tag
readwise reader-list-documents --location archive --tag "research" --category article
# List unseen documents
readwise reader-list-documents --location new --seen false
Reader locations: new (inbox), later, shortlist, archive, feed. When the user says "inbox", use new.
Reading document content
# Get full document details including Markdown content
readwise reader-get-document-details --document-id <id>
# Get all highlights on a document
readwise reader-get-document-highlights --document-id <id>
Saving and creating
# Save a URL — Reader scrapes it automatically
readwise reader-create-document --url "https://example.com/article"
# Save with metadata and tags
readwise reader-create-document --url "https://example.com" --title "My Title" --tags research,important
# Save raw content (provide a unique URL as identifier)
readwise reader-create-document --title "Meeting Notes" --markdown "# Notes from today..." --url "https://me.com#notes-2024"
# Highlight a passage (html-content must match the document's HTML exactly)
readwise reader-create-highlight --document-id <id> --html-content "<p>The key passage</p>" --note "Connects to..."
Organizing
# Move documents between locations (max 50 per call)
readwise reader-move-documents --document-ids <id1>,<id2> --location archive
# Bulk mark as seen
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "seen": true}]'
# Tag management
readwise reader-list-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
# Highlight tags and notes
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 "My note"
Exporting
# Export all documents as Markdown ZIP (async — poll for completion)
readwise reader-export-documents
readwise reader-get-export-documents-status --export-id <id>
# Delta export — only docs updated since last export
readwise reader-export-documents --since-updated "2024-01-01T00:00:00Z"
Readwise Commands
Searching and browsing highlights
# Semantic search across all highlights (books, articles, podcasts, etc.)
readwise readwise-search-highlights --vector-search-term "learning techniques"
# List recent highlights
readwise readwise-list-highlights --page-size 20
# Highlights from a specific book
readwise readwise-list-highlights --book-id <id>
# Highlights from the last month
readwise readwise-list-highlights --highlighted-at-gt "2024-06-01T00:00:00Z"
Creating and editing highlights
# Create a highlight (goes into a book matched by title/author, or "Quotes" if no title)
readwise readwise-create-highlights --highlights '[{"text": "The key insight", "title": "Book Title", "author": "Author Name"}]'
# Update a highlight — change text, add note, manage tags, set color
readwise readwise-update-highlight --highlight-id <id> --note "Updated note" --add-tags concept,review --color blue
# Delete a highlight
readwise readwise-delete-highlight --highlight-id <id>
Daily review
# Get today's spaced repetition review with highlights and interactive review URL
readwise readwise-get-daily-review
Example Workflows
Triage the inbox: List recent saves, read each one, decide what's worth the user's time, and move to the right place.
readwise reader-list-documents --location new --limit 10 --response-fields title,author,summary,word_count,category,saved_at
readwise reader-get-document-details --document-id <id>
readwise reader-move-documents --document-ids <id> --location later
Search across everything: Search both Reader documents and Readwise highlights in parallel to find everything on a topic.
readwise reader-search-documents --query "spaced repetition"
readwise readwise-search-highlights --vector-search-term "spaced repetition"
Quiz on a recent read: Find recently finished documents, pick one, fetch its content and highlights, then quiz the user on what they read.
readwise reader-list-documents --location archive --limit 10 --response-fields title,author,summary,word_count
readwise reader-get-document-details --document-id <id>
readwise reader-get-document-highlights --document-id <id>
Catch up on RSS: Browse recent feed items, surface the best ones, mark the rest as seen.
readwise reader-list-documents --location feed --limit 20 --response-fields title,author,summary,word_count,site_name
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "seen": true}]'
readwise reader-move-documents --document-ids <id> --location later
Save and annotate: Save a URL, highlight key passages, and organize with tags.
readwise reader-create-document --url "https://example.com/article" --tags research
readwise reader-create-highlight --document-id <id> --html-content "<p>Key passage</p>" --note "This connects to..."
readwise reader-add-tags-to-document --document-id <id> --tag-names important,research