readwise-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

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

```bash
readwise login-with-token <token>
```

## Discovering Commands

Every command supports `--help` for full option details:

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

```bash
# Semantic search across all saved documents
readwise reader-search-documents --query "spaced repetition"

# Search only articles saved for later
readwise reader-search-documents --query "machine learning" --category-in article --location-in later,shortlist

# Search by author within the inbox
readwise reader-search-documents --query "AI" --author-search "Simon Willison" --location-in new

# Search documents published after a date
readwise reader-search-documents --query "transformers" --published-date-gt 2024-01-01
```

### Browsing documents

```bash
# List 10 most recent inbox items (minimal fields to save tokens)
readwise reader-list-documents --location new --limit 10 --response-fields title,author,summary,word_count,category,saved_at

# List archived articles tagged "research"
readwise reader-list-documents --location archive --tag research --category article

# List unseen documents in the inbox
readwise reader-list-documents --location new --seen false

# List RSS feed items
readwise reader-list-documents --location feed --limit 20 --response-fields title,author,summary,site_name

# Get a specific document by ID
readwise reader-list-documents --id <document_id>
```

Locations: `new` (inbox), `later`, `shortlist`, `archive`, `feed`. When the user says "inbox", use `new`.

### Reading and highlighting

```bash
# Get full document content as Markdown
readwise reader-get-document-details --document-id <id>

# Get all highlights on a document
readwise reader-get-document-highlights --document-id <id>

# Highlight a passage (html-content must match the document's HTML exactly)
# Get the HTML first via reader-list-documents with --response-fields html_content
readwise reader-create-highlight --document-id <id> --html-content "<p>The exact passage to highlight</p>"

# Highlight with a note and tags
readwise reader-create-highlight --document-id <id> --html-content "<p>Key insight</p>" --note "Connects to spaced repetition research" --tags review,concept
```

### Saving documents

```bash
# Save a URL — Reader scrapes it automatically
readwise reader-create-document --url "https://example.com/article"

# Save with metadata
readwise reader-create-document --url "https://example.com" --title "Great Article" --tags research,ai --notes "Recommended by Alice"

# Save raw Markdown content (provide a unique URL as identifier)
readwise reader-create-document --title "Meeting Notes" --markdown "# Notes from today..." --url "https://me.com#notes-march-2025"
```

### Organizing

```bash
# Move documents between locations (max 50 per call)
readwise reader-move-documents --document-ids <id1>,<id2> --location archive
readwise reader-move-documents --document-ids <id> --location later

# Bulk mark documents as seen
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "seen": true}]'

# Bulk update metadata (title, author, tags, summary, etc.)
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "title": "Better Title", "tags": ["ai", "research"]}]'

# Tags
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

From jamierumbelow/agentfiles, MIT.

More from jamierumbelow/agentfiles