Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scarvy/readwise-reader-cli

Use Readwise Reader 📖 in the Command-line (CLI) 💻
https://github.com/scarvy/readwise-reader-cli

api cli command-line python readwise

Last synced: 1 day ago
JSON representation

Use Readwise Reader 📖 in the Command-line (CLI) 💻

Host: GitHub
URL: https://github.com/scarvy/readwise-reader-cli
Owner: Scarvy
License: mit
Created: 2023-08-10T22:39:43.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2023-09-25T20:13:27.000Z (about 1 year ago)
Last Synced: 2024-11-12T07:55:27.206Z (3 days ago)
Topics: api, cli, command-line, python, readwise
Language: Python
Homepage:
Size: 2.4 MB
Stars: 19
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Reader API Command-Line Interface

![](./images/reader-terminal.png)

This 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.

Also, you can `upload` documents from your browser reading list, such as Chrome ReadingList.

Please note that future updates will include support for additional browsers.

## Installation

Set up a virtual environment and then run:

```bash
pip install readwise-reader-cli
```

## Usage

Before 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).

```bash
export READER_API_TOKEN={your_api_token}
```

The CLI provides the following commands:

```bash
Usage: python -m readercli [OPTIONS] COMMAND [ARGS]...

Interact with your Reader Library

Options:
--help Show this message and exit.

Commands:
add Add Document
lib Library breakdown
list List Documents
upload Upload Reading List File
validate Validate token
```

### List Documents

```bash
Usage: python -m readercli list [OPTIONS]

List Documents

Examples:

```bash
python -m readercli list --location archive
```

```bash
python -m readercli list --location archive --category article
```

```bash
python -m readercli list --location archive --category article --update-after 2023-01-01
```

```bash
python -m readercli list --location archive --category article --update-after 2023-01-01 --layout list
```

```bash
python -m readercli list --location archive --category article --date-range week
```

### Layouts

![table](./images/table.png)

![list_table](./images/list.png)

### Upload a Reading List (Google Chrome support only)

**THINGS TO NOTE:**

- **RATE LIMIT - Due to Reader's API rate limit of 20 requests per minute, a larger list will take a few minutes to upload.**

- **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).**

To `upload` your Chrome Reading List, you first need to download your data from your account, then follow these steps:

1. Navigate to the [Data & Privacy](https://myaccount.google.com/data-and-privacy) section.
2. Find the "Download your data" option and click on it.
3. A list of data to export will appear. Click "Deselect all" and then locate the Chrome section.
4. Click "All Chrome data Included" and select ONLY "ReadingList".
5. Save the downloaded `.html` file to your preferred directory and take note of the file path.
6. Run the `import` command.

```bash
Usage: python -m readercli upload [OPTIONS] INPUT_FILE

Upload Reading List File

Options:
--file-type [html|csv]
--help Show this message and exit.
```

Examples:

```bash
python -m readercli upload /path/to/ReadingList.html
```

```bash
python -m readercli upload --file-type csv /path/to/ReadingList.csv
```

### Add Document

```bash
Usage: python -m readercli add [OPTIONS] URL

Add Document

Options:
--help Show this message and exit.
```

Example:

```bash
python -m readercli add http://www.example.com
```

### Library Overview

```bash
Usage: python -m readercli lib [OPTIONS]

Library breakdown

Options:
-V, --view [category|location|tags]
--help Show this message and exit.
```

```bash
python -m readercli lib

Category Breakdown
┏━━━━━━━━━━━━━┳━━━━━━━┓
┃ Name ┃ Count ┃
┡━━━━━━━━━━━━━╇━━━━━━━┩
│ 🖍️ highlight│ 724 │
│ 📡️ rss │ 391 │
│ ✉️ email │ 363 │
│ 📰️ article │ 264 │
│ 📝️ note │ 140 │
│ 📄️ pdf │ 83 │
│ 🐦️ tweet │ 25 │
│ 📹️ video │ 10 │
│ 📖️ epub │ 0 │
└─────────────┴───────┘

python -m readercli lib --view [location | tags]

Location Breakdown
┏━━━━━━━━━━━┳━━━━━━━┓
┃ Name ┃ Count ┃
┡━━━━━━━━━━━╇━━━━━━━┩
│ 🗄️ archive│ 1124 │
│ 🕑️ later │ 241 │
│ ⭐️ new │ 10 │
│ 📥️ feed │ 2 │
└───────────┴───────┘

python -m readercli lib --view tags

Tags Breakdown
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Name ┃ Count ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ python │ 32 │
│ documentation │ 9 │
│ programming │ 7 │
│ github │ 7 │
│ git │ 6 │
│ packages │ 6 │
│ design-patterns │ 6 │
│ mac │ 1 │
└────────────────────────┴───────┘
```

### Validate Token

```bash
Usage: python -m readercli validate [OPTIONS] TOKEN

Validate token

Options:
--help Show this message and exit.
```

## Main Third-Party Libraries

- [click](https://github.com/pallets/click)
- [pydantic](https://github.com/pydantic/pydantic)
- [requests](https://github.com/psf/requests)
- [rich](https://github.com/Textualize/rich)

## Inspiration

- [starcli](https://github.com/hedyhli/starcli)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.