Reader

Interact with Readwise Reader library using executable scripts.

Quick Start

All Reader operations are available as scripts in the scripts/ subdirectory:

Authentication

Set the READWISE_ACCESS_TOKEN environment variable using one of these methods:

Method 1: Using a .env file

Create a .env file in the project directory:

READWISE_ACCESS_TOKEN=your-token-here

The scripts automatically load environment variables from .env using python-dotenv.

Method 2: Command line

Export in shell:

export READWISE_ACCESS_TOKEN=your-token-here

Or inline for a single command:

READWISE_ACCESS_TOKEN=your-token-here python scripts/list_documents.py

Getting your token

Get your token from: https://readwise.io/access_token

Setup

Install the required dependencies before using the scripts:

pip install -r scripts/requirements.txt

The scripts require:

• httpx - Async HTTP client for API requests
• python-dotenv - Environment variable management

Common Workflows

List documents in a folder

python scripts/list_documents.py --location later --limit 10

Save a URL with tags

echo '{"url": "https://example.com/article", "tags": ["important"]}' | python scripts/create_document.py

Archive a document

echo '{"id": "doc-id", "location": "archive"}' | python scripts/update_document.py

Bulk archive multiple documents

echo '{"updates": [{"id": "doc1", "location": "archive"}, {"id": "doc2", "location": "archive"}]}' | python scripts/bulk_update_documents.py

Error Handling

Errors are written to stderr in JSON format:

{"error": {"type": "...", "message": "...", "hint": "..."}}

Rate Limits

Scripts automatically handle retries for rate limits (429) and server errors (5xx). No action needed unless exit code 3.

Resources

• Usage Guide: references/usage-guide.md