bobolink

bobolink is a small tool that helps user’s save bookmarks on the web. When users save links with bobolink, the HTML of the underlying document is indexed for search.

In practice, this allows you to use bobolink to save some bookmarks, and later quickly find those which contain for example "(songbird OR blackbird) AND NOT finch" in the text of their HTML document.

The bobolink backend is written in clojure. The cli is written in python and is at present the main interface into the bobolink application.

Why

In the past I saved lots of links without the use of a bookmark manager. When I found a new article I’d hoped to reference or read at another time, I simply appended it to a long-running text file I kept locally. A downside to this approach is that URLs alone often lack adequate detail of the contents into the web page, so grep’ing for an article by some keyword in the URL was not always possible.

Bobolink addresses that: one can simply add URLs, search by some keyword and have returned all articles that mention these terms.

Getting Started

$ python -m pip install bobolink
Create an account:
$ bobolink signup
Configure your environment to use your new account:
$ bobolink configure
Thats it. Start saving bookmarks and perform some searches:
$ bobolink add https://en.wikipedia.org/wiki/Bobolink
$ bobolink search dolichonyx
[url]: https://en.wikipedia.org/wiki/Bobolink
[match]: The bobolink Dolichonyx oryzivorus is a small New World blackbird and the only member of the genus Dolichonyx An old name for this species is the Rice Bird from its tendency to feed on cultivated
(Optionally) backup your stored bookmarks from time to time:
$ bobolink export > my-archived-bookmarks.txt

Examples

asciicast

Documentation

bobolink is simply composed of various commands around the CRUD operations of bookmark/user management. To manage your user account there is signup, configure, and reset-password. To manage your bookmarks there is add, search, delete, and export. Several of these commands are documented below, however the CLI itself is thoroughly documented and users can obtain all this information there (and more) as well i.e. bobolink --help or boblink [COMMAND] --help.

signup

bobolink signup [OPTIONS]
Options:
  --email TEXT
  --password TEXT

Creates a new account with the public bobolink instance.

Users should ensure that the supplied email address used is accessible by them as it will be required to recieve communication from bobolink via email for completing certain tasks e.g. password resets.

configure

bobolink configure [OPTIONS]
Options:
  --email TEXT
  --password TEXT

Configure your environment to use your newly created bobolink account.

In practice this command generates and INI file located in $HOME/.bobolink/credentials which contains your bobolink username and currently valid API token which are used to authenticate all requests made from the bobolink CLI. Users wishing to refresh their API tokens can simply rerun this command at any time.

add

bobolink add [OPTIONS] [BOOKMARKS]...

Adds bookmarks to your store.

Accepts a whitespace seperated list of URLs which will be added to your store and made immediately available for search. Users wishing to refresh the searchable content of a bookmark can simply rerun this command with the bookmark URL.

bobolink search [OPTIONS] QUERY
Options:
  --field [url|content]  the bookmark field to search on
  --url-only             only return the URL of a match

Searches a query string against a user’s bookmark store.

When no field is supplied, searches the text content of the HTML page associated with a user’s bookmark.

When passed --field=url, bobolink will only search on the text within the URL of a bookmark.

When searching on content, an attempt is made to highlight where those matches occured in the original HTML. Support for this feature varies by terminal.

Search syntax for bobolink is equivalent to the query language supported by Lucene’s Query Parser. User’s should refer to the Lucene documentation for more info and example usage.

delete

bobolink delete [OPTIONS] [BOOKMARKS]...

Deletes bookmarks from a user’s store.

Accepts a whitespace seperated list of URLs to be deleted from a user’s store. Bookmarks deleted here are immediately purged from search indexes. Non-existent bookmarks are simply ignored.

Small things

It should be noted that bobolink is not a “read-it-later” tool and does not offer any such functionality; searches return snippets of matching text only to highlight where an article matched a user’s search query.

Support

At present bobolink is completely free* for users.

*However, while it was designed to be a low maintenance/low cost app (small tier EC2 server with a few supporting S3 buckets), if the popularity of bobolink grows to dictate that additional compute/storage is necessary, it may be necessary to devise some freemium model to help keep the lights on.

As such user’s are limited to storing up to 250 bookmarks at a time at the moment. If you’d like (entirely optional) you could buy me a coffee to help share the load on some of the associated AWS costs.

Please reach out to johntanza@gmail.com if you have any questions on bobolink. Contributions are always welcome on both the cli and the api