go-org-readwise

This is a very very simple project that sync from readwise API to a set of org files in a folder. It implements just what is needed from the Readwise API to work.

Building and Running

This project uses Nix flakes for development and builds.

With Nix

Building

# Build the project
nix build

# The binary will be available in ./result/bin/
./result/bin/go-org-readwise --help

Running

# Run directly with nix run
nix run . -- -targetFolder /path/to/org/files -apiKeyFile /path/to/key

# Or using environment variable for API key
READWISE_KEY=your_key nix run . -- -targetFolder /path/to/org/files

# Archive URLs using monolith (requires monolith to be installed)
READWISE_KEY=your_key nix run . -- -targetFolder /path/to/org/files -archiveURLs

Development Shell

# Enter development shell with Go and other dependencies
nix develop

# Inside the dev shell, use standard Go commands
go build
go test -v ./...
go run . -targetFolder /path/to/org/files

Without Nix

If you have Go installed, you can use standard Go commands:

# Build
go build -v ./...

# Run tests
go test -v ./...

# Run the tool
go run . -targetFolder /path/to/org/files -apiKeyFile /path/to/key

# Run with URL archiving
go run . -targetFolder /path/to/org/files -apiKeyFile /path/to/key -archiveURLs

Features

URL Archiving

The tool supports archiving document URLs using the monolith command-line tool. When enabled with the -archiveURLs flag:

• Archives are stored in a .archive folder within the target directory
• Archive files use the same denote naming convention as the org files, with .html extension
• The org file includes an #+property: ARCHIVE: header linking to the archived HTML file
• If archiving fails (e.g., monolith not installed or URL unreachable), the sync continues with a warning

Requirements: The monolith command must be installed and available in your PATH.

Readwise API

We are only going to implement the export part of the API as, this should be the only one we need.

If you want to pull all of the highlights from a user’s account into your service (eg notetaking apps, backups, etc) this endpoint is all you need!

Tasks

Explore v3 API

In theory I could rely on the v3 API to get documents that are “archived” but have no highlights. Not sure this is something I want to do though.

I doesn’t have highlight so… I would have to query both.

See https://readwise.io/reader_api.