reticule

Reticule is an extremely minimal, self-hosted alternative to bookmarking services like Pocket/Instapaper/Wallabag that relies on a feed reader of your choice (like Miniflux, Vore, Newsboat, and others) to view your saved links.

What it does:

$ curl http://localhost:8080/feed?key=EXAMPLE
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom">

<channel>
	<title>my-saved-links</title>
	<description>example</description>
	<generator>Reticule (devel)</generator>
	<language>en</language>
	<pubDate>2024-01-04 23:13:24.763009482 -0600 CST</pubDate>
	<item>
		<title>reticule</title>
		<link>https://git.cyberia.club/reese/reticule</link>
		<author>reese</author>
		<description>👛 a very simple REST API for saving online articles to read later</description>
		<guid>81b1efe5-7877-462d-b315-1fd4299f1938</guid>
		<pubDate>2024-01-04 23:13:24.763009482 -0600 CST</pubDate>
		<content:encoded>&lt; ....

Installation

Flakes

Currently the only supported installation method is with Nix Flakes. This flake provides the reticule package and a module for using it declaratively with NixOS. Here is an example flake.nix that you can copy from if your system is configured with Flakes:

{
  inputs = {
    reticule.url = "git+https://git.cyberia.club/reese/reticule.git";
  };
  
  outputs = { reticule, ... }@inputs: {
    nixosConfigurations.hostname = nixpkgs.lib.nixosSystem rec {
      modules = [
        reticule.nixosModules.reticule
      ];
    };
  };
}

The possible configuration values can be found here.

From source

You can also download the source code from this repository and build it like any other Go binary. Once built, see ./reticule -h for usage info.

Quickstart:

$ go run . -db-path ./reticule-data -address 127.0.0.1 -port 8080 -api-key EXAMPLE  -feed-name test -feed-desc my-test-feed
[INFO] [cloverDB] creating database directory './reticule-data' (/home/forest/Desktop/git/reticule/reticule-data)
[INFO] Starting server on 127.0.0.1:8080

If you get module errors, try go clean -modcache (Note: this may take a while)

Usage

Web browser bookmarklet

Create a new bookmark in your browser with the name "Save to Reticule" and set the URL to the following:

javascript:(()=>{window.open("<SERVER_ADDRESS>/add?key=<API_KEY>&url="+encodeURIComponent(location),"_blank","noreferrer,noopener")})()

Important: Make sure you change <SERVER_ADDRESS> and <API_KEY> to the values you configured your server with.

Go to a webpage that you want to save, click the bookmarklet, and voila! It should open a new tab with a message that it was saved successfully, which you can then close.

Android

1. Install HTTP Shortcuts from F-Droid or the Play Store.
2. Download reticule_http_shortcut.json from this repo to your device.
3. Open HTTP Shortcuts, tap the vertical 3 dots in the top right corner, tap "Import/Export", then tap "Import from file". Select the json file you downloaded earlier.
4. Go back to the main page, tap the 3 dot button again, then tap "Variables", and edit the values of reticule_instance and reticule_api_key to match those of your instance.
5. Try using the share button in an app. A new item "Send to..." with the HTTP Shortcuts icon should appear on the share sheet. You can also save an article by tapping the shortcut inside the HTTP Shortcuts app itself and pasting the URL.

RSS feed reader

The RSS feed is available at /feed?key=<API_KEY>. Add your key, or remove everything after ? if you set public to true, and then add it to your feed reader of choice. If it doesn't work in your reader, open an issue and I will try my best to resolve it!

Acknowledgements

The purple coin purse favicon comes from OpenMoji, which is licensed under CC BY-SA 4.0.