addrb is a super lightweight command line address book that supports VCARD synchronization via CardDAV, output templating using text/template, as well as JSON output. And it can also list birthdays!



addrb, the command line address book. It’s super lightweight, yet it supports CardDAV sync!


go build .


Either export all necessary variables to your ENV or set them as command line flags:

export ADDRB_DB='...'

If you’re using Baïkal for example, you would export something like this as CARDDAV_ENDPOINT:


The ADDRB_DB is the local contacts database in order to not need to contact the CardDAV for every lookup. You might set it to something like this:

export ADDRB_DB=~/.cache/addrb.db

When addrb is launched for the first time, it requires the -r flag to refresh the contacts and sync them locally:

addrb -r john doe

This command will connect to the CardDAV server, sync all address books/contacts locally and perform a lookup for john doe. It will display you the contact(s) if any was found.

You can also refresh without querying:

addrb -r

This way you could create a cron job that refreshes addrb in the background, e.g. every three hours:

crontab -e
0 */3 * * * sh -c 'addrb -r'

You can also output contacts as JSON format using the -j flag:

addrb -j john doe

Find more flags and info with addrb --help.


You can customize the regular output using templating. The template can either be passed using the --template <file> flag or by exporting ADDRB_TEMPLATE in the in the environment.

The templating format is the Go standard text/template format. The following special functions are available:

  • RenderPhoto for rendering a base64 string as image (usually the contact PHOTO)
  • RenderAddress for rendering a contact address

Available property names that are available can be found by displaying a contact as JSON (using the -j flag). E.g. “FN” is the full name, which can be retrieved using e.g. the .PreferredValue method:

{{ .PreferredValue "FN" }}

Other methods that are available can be found here, with the most useful ones probably being .PreferredValue, .Value, and .Values (for arrays).

An example template can be found here. To make use of the template, you can copy it to e.g. ~/.config/addrb.tmpl and have ADDRB_TEMPLATE=~/.config/addrb.tmpl exported in your .zshrc/.bashrc/etc.


  • Q: Does addrb write/modify any contact information? A: Nope, so far it’s read-only and does not support updating vCards, hence it won’t mess with your data.
  • Q: Can I use it with my local address book? A: Nope, as of right now addrb only supports CardDAV servers to sync with.
  • Q: Does it support HTTP Digest auth? A: Nope, only HTTP Basic auth.
  • Q: The text/template stuff doesn’t work for me, can I make addrb output contact data differently? A: Yes, you can use the -j flag and have it output pure JSON, which you can then process using e.g. jq.

Updates GitHub

Enjoyed this? Support me via Monero, Bitcoin, Lightning, or Ethereum!  More info.