Skip to content
No description, website, or topics provided.
Python TeX Shell
Branch: master
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.


Ref is a lightweight command-line reference manager. It is built on python and vim.

Ref is released under the terms of the MIT license.



You'll need a recent vim, compiled with python 2.7 support.

On ubuntu the ones in apt-get will do, on Mac OS X use brew install python and brew install vim. On Mac OS X you'll also need poppler for the pdftotext command line tool: brew install poppler


git clone
cd ref
python install


Set your base_dir and google scholar Cookie in ~/.ref.conf, for example:

"base_dir"  : "~/Dropbox/ref",
"Cookie"    : "<<Obtained from visiting google scholar with Live HTTP headers>>"

Setting your base_dir to a dropbox folder will enable automatic syncing between your Dropbox-enabled computers. The database and pdf's will be saved in the base_dir.

The Cookie you'll have to set manually after you added a few document and google scholar will start blocking the randomly generated cookies; you can skip this for now.

  • Go to, search for something
  • On the search results, go to settings > Bibliography manager > Show links to import citations into BibTeX
  • Do another search on and with Live HTTP headers capture the Cookie


Type "ref" on the command line to see the main screen which is a vim session with two panes, split horizontally. Move around like usual in vim with hjkl and jump between the panes with ctrl+W+W

  • :Add rel/path/to/downloaded/pdf will add the document and fetch the bibtex from google scholar based on the title from the document.
  • :Fetch if the fetched bibtex was wrong, fix the title then type :Fetch to try again.
  • Search by typing //keyword where the keyword could be an author name or words from the title.
  • To clear a search just enter // (i.e. search without any keyword)
  • You can still use vim's regular search with /keyword
  • Exit with q
  • ctrl+U toggles the U flag (U for Unread)
  • :Delete deletes document



Pro tips

If you're switching from another reference manager or just a messy folder of pdfs, you can open a python session, type import ref; ref.init() and ref.import_dir(/path/to/your/messy/folder)

The codebase consists of two files with less than 600LoC, it's easy to change things if needed.

You can’t perform that action at this time.