{"id":20208446,"url":"https://github.com/scarvy/readwise-reader-cli","last_synced_at":"2025-04-10T12:56:34.100Z","repository":{"id":196548020,"uuid":"677163210","full_name":"Scarvy/readwise-reader-cli","owner":"Scarvy","description":"Use Readwise Reader 📖 in the Command-line (CLI) 💻","archived":false,"fork":false,"pushed_at":"2023-09-25T20:13:27.000Z","size":2519,"stargazers_count":19,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-12T07:55:27.206Z","etag":null,"topics":["api","cli","command-line","python","readwise"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Scarvy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-08-10T22:39:43.000Z","updated_at":"2024-11-03T13:09:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"dd044fa1-8cdf-4785-afd2-641b08254505","html_url":"https://github.com/Scarvy/readwise-reader-cli","commit_stats":null,"previous_names":["scarvy/readwise-reader-cli"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Scarvy","download_url":"https://codeload.github.com/Scarvy/readwise-reader-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224573465,"owners_count":17333807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","cli","command-line","python","readwise"],"created_at":"2024-11-14T05:35:41.006Z","updated_at":"2024-11-14T05:35:41.577Z","avatar_url":"https://github.com/Scarvy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Reader API Command-Line Interface\n\n![](./images/reader-terminal.png)\n\nThis repository provides a command-line interface (CLI) for interacting with [Readwise's Reader API](https://readwise.io/reader_api). This tool allows you to interact with the API directly from your command line, making it easy to `add` and `list` documents from your Reader library.\n\nAlso, you can `upload` documents from your browser reading list, such as Chrome ReadingList.\n\nPlease note that future updates will include support for additional browsers.\n\n## Installation\n\nSet up a virtual environment and then run:\n\n```bash\npip install readwise-reader-cli\n```\n\n## Usage\n\nBefore using the CLI, make sure to set the READER_API_TOKEN environment variable. You can obtain your API token [here](https://readwise.io/access_token).\n\n```bash\nexport READER_API_TOKEN={your_api_token}\n```\n\nThe CLI provides the following commands:\n\n```bash\nUsage: python -m readercli [OPTIONS] COMMAND [ARGS]...\n\n  Interact with your Reader Library\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  add       Add Document\n  lib       Library breakdown\n  list      List Documents\n  upload    Upload Reading List File\n  validate  Validate token\n```\n\n### List Documents\n\n```bash\nUsage: python -m readercli list [OPTIONS]\n\n  List Documents\n\nOptions:\n  -l, --location [new|archive|later|feed]\n                                  Document(s) location\n  -c, --category [article|tweet|pdf|epub|email|note|video|highlight|rss]\n                                  Document(s) category\n  -a, --update-after [%Y-%m-%d|%Y-%m-%dT%H:%M:%S|%Y-%m-%d %H:%M:%S]\n                                  Updated after date in ISO format. Default:\n                                  last 24hrs.\n  -d, --date-range TEXT           View documents updated after choosen time:\n                                  today, week, month.\n  -L, --layout [table|list]       Display documents either as a list or table.\n                                  Default: table.\n  -n, --num-results INTEGER       The number of documents to show.\n  -P, --pager                     Use to page output.\n  --help                          Show this message and exit.\n```\n\nExamples:\n\n```bash\npython -m readercli list --location archive\n```\n\n```bash\npython -m readercli list --location archive --category article\n```\n\n```bash\npython -m readercli list --location archive --category article --update-after 2023-01-01\n```\n\n```bash\npython -m readercli list --location archive --category article --update-after 2023-01-01 --layout list\n```\n\n```bash\npython -m readercli list --location archive --category article --date-range week\n```\n\n### Layouts\n\n![table](./images/table.png)\n\n![list_table](./images/list.png)\n\n### Upload a Reading List (Google Chrome support only)\n\n**THINGS TO NOTE:**\n\n- **RATE LIMIT - Due to Reader's API rate limit of 20 requests per minute, a larger list will take a few minutes to upload.**\n\n- **LACK OF READING LIST APIs - There is no API to pull your ReadingList from Google, but it is being looked at [here](https://bugs.chromium.org/p/chromium/issues/detail?id=1238372).**\n\nTo `upload` your Chrome Reading List, you first need to download your data from your account, then follow these steps:\n\n1. Navigate to the [Data \u0026 Privacy](https://myaccount.google.com/data-and-privacy) section.\n2. Find the \"Download your data\" option and click on it.\n3. A list of data to export will appear. Click \"Deselect all\" and then locate the Chrome section.\n4. Click \"All Chrome data Included\" and select ONLY \"ReadingList\".\n5. Save the downloaded `.html` file to your preferred directory and take note of the file path.\n6. Run the `import` command.\n\n```bash\nUsage: python -m readercli upload [OPTIONS] INPUT_FILE\n\n  Upload Reading List File\n\nOptions:\n  --file-type [html|csv]\n  --help                  Show this message and exit.\n```\n\nExamples:\n\n```bash\npython -m readercli upload /path/to/ReadingList.html\n```\n\n```bash\npython -m readercli upload --file-type csv /path/to/ReadingList.csv\n```\n\n### Add Document\n\n```bash\nUsage: python -m readercli add [OPTIONS] URL\n\n  Add Document\n\nOptions:\n  --help  Show this message and exit.\n```\n\nExample:\n\n```bash\npython -m readercli add http://www.example.com\n```\n\n### Library Overview\n\n```bash\nUsage: python -m readercli lib [OPTIONS]\n\n  Library breakdown\n\nOptions:\n  -V, --view [category|location|tags]\n  --help                          Show this message and exit.\n```\n\n```bash\npython -m readercli lib\n\n  Category Breakdown\n┏━━━━━━━━━━━━━┳━━━━━━━┓\n┃ Name        ┃ Count ┃\n┡━━━━━━━━━━━━━╇━━━━━━━┩\n│ 🖍️ highlight│   724 │\n│ 📡️ rss      │   391 │\n│ ✉️ email     │   363 │\n│ 📰️ article  │   264 │\n│ 📝️ note     │   140 │\n│ 📄️ pdf      │    83 │\n│ 🐦️ tweet    │    25 │\n│ 📹️ video    │    10 │\n│ 📖️ epub     │     0 │\n└─────────────┴───────┘\n\npython -m readercli lib --view [location | tags]\n\n Location Breakdown\n┏━━━━━━━━━━━┳━━━━━━━┓\n┃ Name      ┃ Count ┃\n┡━━━━━━━━━━━╇━━━━━━━┩\n│ 🗄️ archive│  1124 │\n│ 🕑️ later  │   241 │\n│ ⭐️ new    │    10 │\n│ 📥️ feed   │     2 │\n└───────────┴───────┘\n\npython -m readercli lib --view tags\n\nTags Breakdown\n┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓\n┃ Name                   ┃ Count ┃\n┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩\n│ python                 │    32 │\n│ documentation          │     9 │\n│ programming            │     7 │\n│ github                 │     7 │\n│ git                    │     6 │\n│ packages               │     6 │\n│ design-patterns        │     6 │\n│ mac                    │     1 │\n└────────────────────────┴───────┘\n```\n\n### Validate Token\n\n```bash\nUsage: python -m readercli validate [OPTIONS] TOKEN\n\n  Validate token\n\nOptions:\n  --help  Show this message and exit.\n```\n\n## Main Third-Party Libraries\n\n- [click](https://github.com/pallets/click)\n- [pydantic](https://github.com/pydantic/pydantic)\n- [requests](https://github.com/psf/requests)\n- [rich](https://github.com/Textualize/rich)\n\n## Inspiration\n\n- [starcli](https://github.com/hedyhli/starcli)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarvy%2Freadwise-reader-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscarvy%2Freadwise-reader-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarvy%2Freadwise-reader-cli/lists"}