skip to navigation
skip to content

goobook 1.4

Search your google contacts from the command-line or mutt.

Latest Version: 1.9

GooBook -- Access your Google contacts from the command line.

.. contents:: **Table of Contents**


The purpose of GooBook is to make it possible to use your Google Contacts from
the command-line and from MUAs such as Mutt.
It can be used from Mutt the same way as abook.

Installation Instructions

There is a number of ways to install Python software.

- Using pip
- Using easy_install
- Using a source tarball
- Using source directly from gitorius
- From a distribution specific repository (Arch Linux AUR)

pip or easy_install

This is the recommended way to install goobook for most users.
When installing this way you will not need to download anything manually.

Run pip or easy_install::

$ pip install goobook
$ easy_install -U goobook

easy_install is part of setuptools which should come with most distributions,
pip is a newer replacement.

Source installation

Download the source tarball, uncompress it, then run the install command::

$ tar -xzvf goobook-*.tar.gz
$ cd goobook-*
$ sudo python ./ install

Upgrading from < 1.0

If you are upgrading from a pre 1.0 version you will have to remove the old
cachefile and create a new configuration.


For most users it will be enough to add an entry to your ~/.netrc::

password secret

NOTE: The netrc implementation in Python don't support passwords with spaces, use the .goobookrc or keyring instead.

To get access too more settings you can create a configuration file::

goobook config-template > ~/.goobookrc

It will look like this::

# "#" or ";" at the start of a line makes it a comment.
# If not given here, email and password is taken from .netrc using
# machine
;password: top secret
# or if you want to get the password from a commmand:
;passwordeval: gpg --batch -d ~/.mutt/pw.gpg
# The following are optional, defaults are shown
;cache_filename: ~/.goobook_cache
;cache_expiry_hours: 24

If you set the password to "prompt" you will be prompted each time the password is needed
but this does not work well with mutt.

Instead of being a plain config file ``.goobookrc`` can be an executable,
in which case it's output will be used as configuration.

For example if you want to store your configuration encrypted with GnuPG as ``.goobookrc.gpg``
you can use a ``.goobookrc`` like this::

gpg --no-tty --use-agent -q -d ~/.goobookrc.gpg

You will need to have a appropriate gpg-agent/pinentry setup, you will not be prompted
for the gpg passphrase on the console.

Similarly, goobook supports authentication by keyring_. The keyring package
supports multiple backends, depending on your
environment. You should configure it to point to the one you're using by
default. To use this option, set your e-mail address in the config file but
leave the password field commented out (or blank). You need to have a password
for the "gmail" service and your e-mail address stored in the keyring. There
are several ways to achieve this, here is one::

$ python
>>> import keyring
>>> keyring.set_password("gmail", "", "secret")

.. _keyring:

Proxy settings

If you use a proxy you need to set the https_proxy environment variable.


If you want to use goobook from mutt.

Set in your .muttrc file::

set query_command="goobook query '%s'"

to query address book. (Normally bound to "Q" key.)

If you want to be able to use <tab> to complete email addresses instead of Ctrl-t add this:

bind editor <tab> complete-query

To add email addresses (with "a" key normally bound to create-alias command)::

macro index,pager a "<pipe-message>goobook add<return>" "add the sender address to Google contacts"

If you want to add an email's sender to Contacts, press a while it's selected in the index or pager.


To query your contacts::

$ goobook query QUERY

The add command reads a email from STDIN and adds the From address to your Google contacts::

$ goobook add

The cache is updated automatically according to the configuration but you can also force an update::

$ goobook reload

For more commands see::

$ goobook -h


$ goobook COMMAND -h

Links, Feedback and getting involved

- Home page:
- PyPI home:
- Mailing list:
- Issue tracker:
- Code Repository:


1.4 2012-11-10
* No longer necessary to configure goobook to be able to generate a configuration template...
* Fixed issue 28: No Protocol is set on GTalk IM
* Fixed issue 32: Encoding problem of unicode chars on non unicode terminal.
* Fixed issue 34: Unable to query due to keyring/DBus regression
* Fixed issue 35: passwordeval
* Fixed issue 36: When the contact has no title mutt will use the extra_str as the title.

1.4a5 never released
* Correctly decode encoded From headers, by Jonathan Ballet
* Fixed IM without protocol, Issue 26
* Fixed encoding issues on OS X, Issue 33
* passwordeval, get password from a command by Zhihao Yuan

1.4a4 2011-02-26

* Fixed bug in parsing postal addresses.
* Adjusted output format for postal addresses.

1.4a3 2011-02-26

* Added contacts are now added to "My Contacts", this fixes problem with
searching now finding contacts you have added with goobook.
* Searches also matches on phonenumber (Patch by Marcus Nitzschke).
* Detailed, human readable, search results (Patch by Marcus Nitzschke).

1.4a2 2010-10-26

* When a query match a email-address, only show that address and not
all the contacts addresses.
* Added option to filter contacts that are in no groups (default on).

1.4a1 2010-09-24

* Fixed mailing to groups
* Improved some error messages
* Isssue 20: Encoding on some Mac OS X
* Issue 21: Cache file never expires
* Support for auth via keyring

1.3 2010-07-17

No changes since 1.3rc1

1.3rc1 2010-06-24

* Support for executable .goobookrc (replaces direct GnuPG support)
* Faster, more compact cache
* dump commands no longer use the cache
* Caching most contact data but not all

1.3a1 2010-04-21

* Python 2.5 compability
* Added flags --verbose and --debug
* Added possibility to add a contact from the command-line.
* Added possibility to prompt for password.
* New command: dump_contacts
* New command: dump_groups
* New dependency, hcs_utils
* Now caching all contact data.
* Support for using a GnuPG encrypted config file (later replaced).
* Fixed bug when checking for the config file.
* Major refactoring

1.2, 2010-03-12

* Issue 14: Only search in these fields: name, nick, emails, group name.
In 1.1 the group URL was also searched, which gave false positives.
* Auto create cache if it doesn't exist.

1.1, 2010-03-10

* Use current locale to decode queries.
* Encode printed text using current locale.
* Added option to specify different configfile.
* Some documentation/help updates.
* The .goobookrc is now really optional.
* Added config-template command.
* Issue 13: Added support for contact groups.
* New cache format, no longer abook compatible (JSON).

1.0, 2010-02-20

* Issue 2: BadAuthentication error can create a problematic cache file so
subsequent runs fail
* Issue 6: cache management needs improvements
- reload, force refresh command
- configurable cache expiry time
* Issue 7: Should probably set safe permissions on settings.pyc
* Issue 8: 'add' doesn't strip extraneous quotation marks
* Issue 9: Indentation error when run without arguments
* Issue 10: Query doesn't browse nicknames
* New abook compatible cache format.
* sort results
* Using SSL
* New config format
* .netrc support
* Supports adding non-ASCII From: headers.

r8, 2009-12-10

File Type Py Version Uploaded on Size
goobook-1.4.tar.gz (md5) Source 2012-11-10 33KB