reader

# Reader Interact with Readwise Reader library using executable scripts. ## Quick Start All Reader operations are available as scripts in the `scripts/` subdirectory: | Script | Purpose | Input | |--------|---------|-------| | `list_documents.py` | Query documents | CLI flags | | `create_document.py` | Save URL/content | JSON payload | | `update_document.py` | Modify document | JSON payload | | `bulk_update_documents.py` | Batch modify (max 50) | JSON payload | | `delete_document.py` | Remove documents | JSON payload | | `list_tags.py` | List all tags | CLI 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 Code | Meaning | Action | |-----------|---------|--------| | 0 | Success | Parse stdout | | 1 | API error | Check stderr for details | | 2 | Auth error | Verify `READWISE_ACCESS_TOKEN` | | 3 | Rate limit | Wait and retry | | 4 | Invalid input | Fix 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](references/usage-guide.md)