No description, website, or topics provided.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


About Shelvd

Shelvd is a reading tracking app inspired by Bkkeepr, made by James Bridle and now sadly mothballed (

The app works off ISBNs and short input messages to track what you've been reading and how much you've read. It has a web interface and a twitter interface and runs on Heroku. Book data comes from Google Books API.

This is the second version of the app, run on Heroku as opposed to Google App Engine. It's actually 2 apps: Shelvd, that does the bulk of the work described in the paragraph above; and Shelvd_Twitter, which simply connects to the Twitter streaming API, keeps that connection open and posts any DMs to Shelvd.

Set up

  1. Set up a Twitter account to carry messages to and from the app.
  2. Follow this Twitter account from your regular account & have this account follow your regular account
  3. Generate the necessary keys and tokens for API usage (see below in "Required Environment Variables")

Required Environment Variables

From Twitter:

  • TWITTER_HANDLE (the handle from which you'll be posting DMs to the app, and to which you'd like notifications sent)

From Google Books API:

Input grammar

(where 9780123123123 is a sample ISBN)

To start a book:

9780123123123 start
9780123123123 begin

To give the book a nickname (an easier-to-remember identifier than the ISBN):

9780123123123 nickname

NB 1: this must be done after first starting a book NB 2: after setting a nickname, you can use it anywhere instead of the ISBN

To note the page you're up to:

9780123123123 196
nickname 196

NB: this must be done after first starting a book

To note the % you're up to (Kindle uses % instead of page numbers):

9780123123123 8%
nickname 8%

NB: this must be done after first starting a book

To finish a book (once you've reached the end):

9780123123123 end
nickname end
9780123123123 finish
nickname finish

To abandon a book (stop reading at your current page):

9780123123123 abandon
nickname abandon