Reader#

Interact with Readwise Reader library using executable scripts.

Quick Start#

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

ScriptPurposeInputlist_documents.pyQuery documentsCLI flagscreate_document.pySave URL/contentJSON payloadupdate_document.pyModify documentJSON payloadbulk_update_documents.pyBatch modify (max 50)JSON payloaddelete_document.pyRemove documentsJSON payloadlist_tags.pyList all tagsCLI flags

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:

bash

READWISE_ACCESS_TOKEN=your-token-here

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

Method 2: Command line#

Export in shell:

bash

export READWISE_ACCESS_TOKEN=your-token-here

Or inline for a single command:

bash

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:

bash

pip install -r scripts/requirements.txt

Common Workflows#

List documents in a folder#

bash

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

Save a URL with tags#

bash

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

Archive a document#

bash

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

Bulk archive multiple documents#

bash

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

Error Handling#

Exit CodeMeaningAction0SuccessParse stdout1API errorCheck stderr for details2Auth errorVerify READWISE_ACCESS_TOKEN3Rate limitWait and retry4Invalid inputFix payload/flags

Errors are written to stderr in JSON format:

json

{"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