Sync your Kobo highlights to hardcover.app!
Here is an example for the book Crooked Kingdom by Leigh Bardugo:
K - Kobo|kepub Scribe - Someone who writes stuff to a new location
ps. add me on hardcover 🤓 https://hardcover.app/@countmancy
- Download and install nickelmenu
- Download the latest release of
kscribblerfrom the releases page - Install
kscribbleron your Kobo:- Connect your Kobo to your computer and mount the device
- Navigate to the
.kobodirectory on your Kobo (might need to show hidden files) - Copy the
KoboRoot.tgzinto this directory and unmount the device safely. This will trigger a reboot and upgrade.
- Remount the device and navigate to
/mnt/onboard/.adds/kscribbler.- If you don't see this directory check for
/mnt/onboard/.adds/kscribbler
- If you don't see this directory check for
- Copy the example config file:
cp config.env.example config.env - Connect to Hardcover, either:
- Sign in (recommended): with WiFi on, open a book, tap the top of the screen and tap the K icon in the reading menu, then
Sign in to Hardcover. Scan the QR code (or visit the link and enter the code), approve, then tapContinue. The token is saved to/mnt/onboard/.adds/kscribbler/token.jsonand refreshed automatically. - Personal access token: add it to
HARDCOVER_API_TOKENinconfig.env. A Hardcover Personal Access Token (PAT) with the necessary permissions (read:me,read:catalog,write:library) can be generated directly from this link.
- Sign in (recommended): with WiFi on, open a book, tap the top of the screen and tap the K icon in the reading menu, then
From the main menu of your Kobo device open nickelmenu and select Upgrade Kscribbler to download and install the latest version.
The download is verified against the release's checksums.txt before it is installed.
UPDATE_CHANNELinconfig.envpicks whatUpgrade Kscribblerinstalls:stable(default),testing, or a release tag such asv1.4.0to pin or roll back.testingis a rolling pre-release published by the Testing Build workflow. Run it from the Actions tab on any branch, or push to atest/**branch.- With the debug options visible (
Toggle Visibility of Kscribbler Options),Kscribbler Install Testing BuildandKscribbler Reinstall Stable Buildinstall that channel right away, even if it is already installed. - From a shell:
/mnt/onboard/.adds/kscribbler/upgrade.sh [stable|testing|<tag>] [--force]
The K icon in the reading menu has Sign in to Hardcover and Sync highlights now.
Once installed nickelmenu should have a new entry in the right corner of reading view that will trigger a sync when clicked.
This will trigger kscribbler to generate its database of quotes and upload them to hardcover.app.
WARNING: This will attempt to upload all quotes from all books on the device. If you want to tame this you will need to manipulate the kscribblerdb yourself. More info below.
The quotes are uploaded to hardcover.app based on the book's ISBN. See the note below or the troubleshooting section if quotes are not being uploaded.
- If your book doesn't have an ISBN saved to the kobo device's database you can highlight the book's ISBN on its copyright page and
kscribblerwill attempt to parse it and save it to the book's metadata.- A note with
kscrib:<you isbn number with no angle bracketscan be added anywhere in the book to manually set the ISBN - Can be useful for sideloaded books
- A note with
All configuration is done via /mnt/onboard/.adds/kscribbler/config.env. See config.env.example for a template.
| Variable | Default | Description |
|---|---|---|
HARDCOVER_API_TOKEN |
(optional when signed in) | Your Hardcover Personal Access Token (PAT). Can be generated with required scopes here |
UPLOAD_ANNOTATIONS |
false |
Set to true to upload annotations (notes) alongside quotes. When enabled, the highlighted passage and your note are combined into a single journal entry separated by --- Personal Annotation --- |
HARDCOVER_CLIENT_ID |
(built in) | Override the OAuth client ID used by sign-in |
PRIVACY |
public |
Privacy level for uploaded journal entries. Options: public, followers, private |
- Logs are stored in
/mnt/onboard/.adds/kscribbler/kscribbler.log - If you are having issues with the quotes not being uploaded, check that hardcover.app has an edition for the ISBN.
- The database of quotes is stored at
/mnt/onboard/.adds/kscribbler/kscribblerdb - This is a sqlite database with two tables:
booksandquotes - You can manipulate this database directly if you want to control what gets uploaded by setting
kscribbler_uploadedto1for quotes you don't want uploaded telnet/sshinto the kobo is possible and allows for manually runningkscribblerif so desired- From the main Kobo screen you can open nickelmenu and
Toggle Visibility of Kscribbler Optionsto run the following commands:kscribbler --initwill initialize the database but not upload anythingkscribbler --mark-all-as-uploadedwill initialize the database, mark all found quotes as upload but will not upload anything- Useful for testing/migrating
- The initial output is displayed but truncated. Full output is in the log file
- Star the repository ⭐
- File bug reports
- Submit pull requests
- Suggest improvements
- Share the project with others if you find it useful
- hardcover-quotes -> Display hardcover reading journal quotes in your terminal or on a trmnl e-ink display
- simpleISBN -> A simple library to parse and convert ISBNs