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 |
|---|
| INLINECODE1 | Query documents | CLI flags |
| INLINECODE2 |
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:
CODEBLOCK0
The scripts automatically load environment variables from .env using python-dotenv.
Method 2: Command line
Export in shell:
CODEBLOCK1
Or inline for a single command:
CODEBLOCK2
Getting your token
Get your token from: https://readwise.io/access_token
Setup
Install the required dependencies before using the scripts:
CODEBLOCK3
Common Workflows
List documents in a folder
CODEBLOCK4
Save a URL with tags
CODEBLOCK5
Archive a document
CODEBLOCK6
Bulk archive multiple documents
CODEBLOCK7
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:
CODEBLOCK8
Rate Limits
Scripts automatically handle retries for rate limits (429) and server errors (5xx).
No action needed unless exit code 3.
Resources
Reader
使用可执行脚本与Readwise Reader库进行交互。
快速入门
所有Reader操作均可通过scripts/子目录中的脚本执行：
| 脚本 | 用途 | 输入 |
|---|
| listdocuments.py | 查询文档 | 命令行参数 |
| createdocument.py |
保存URL/内容 | JSON负载 |
| update_document.py | 修改文档 | JSON负载 |
| bulk
updatedocuments.py | 批量修改（最多50个） | JSON负载 |
| delete_document.py | 删除文档 | JSON负载 |
| list_tags.py | 列出所有标签 | 命令行参数 |
身份验证
使用以下方法之一设置READWISEACCESSTOKEN环境变量：
方法1：使用.env文件
在项目目录中创建.env文件：
bash
READWISEACCESSTOKEN=你的令牌
脚本会自动使用python-dotenv从.env加载环境变量。
方法2：命令行
在shell中导出：
bash
export READWISEACCESSTOKEN=你的令牌
或单次命令内联：
bash
READWISEACCESSTOKEN=你的令牌 python scripts/list_documents.py
获取你的令牌
从以下地址获取你的令牌：https://readwise.io/access_token
环境配置
使用脚本前安装所需依赖：
bash
pip install -r scripts/requirements.txt
常见工作流程
列出文件夹中的文档
bash
python scripts/list_documents.py --location later --limit 10
保存带标签的URL
bash
echo {url: https://example.com/article, tags: [important]} | python scripts/create_document.py
归档文档
bash
echo {id: doc-id, location: archive} | python scripts/update_document.py
批量归档多个文档
bash
echo {updates: [{id: doc1, location: archive}, {id: doc2, location: archive}]} | python scripts/bulkupdatedocuments.py
错误处理
API错误 | 检查标准错误输出获取详情 |
| 2 | 身份验证错误 | 验证READWISE
ACCESSTOKEN |
| 3 | 速率限制 | 等待后重试 |
| 4 | 无效输入 | 修复负载/参数 |
错误以JSON格式写入标准错误输出：
json
{error: {type: ..., message: ..., hint: ...}}
速率限制
脚本会自动处理速率限制（429）和服务器错误（5xx）的重试。
除非退出码为3，否则无需任何操作。
资源
