addrbook - A CLI contact management program

Files

.gitignore

README.md

addrbook

make_db.sql

README.md

Addrbook - a contact management program

Manage your contacts with your favorite terminal text editor!

Less than 300 lines of Ruby. Written by hand by a human.

Addrbook was created to work with the Aerc email client, but is completely<br>useable from the command line and might also work within other email clients so<br>long as they can launch terminal applications.

If you want to jump right in and start using it, head down to the<br>&lsquo;Configuration&rsquo; section.

Text files and a database?

Relational databases are great and text files are great. So which did I choose<br>for Addrbook? Both! I chose a database (SQLite) to store the address book<br>entries as proper relation database. But I also chose to interact with the<br>entries as text files. This gives us the best of both worlds!

When you view an entry, you are looking at a text file, but the data came from<br>the database.

You edit an entry by editing the text file in your favorite text editor. Then<br>Addrbook imports your changes back into the database.

(----------) +----------+<br>( ) | |<br>( DB ) | .txt |<br>( ) | /<br>(----------) +---------/

^ ^<br>Stored here Edited here

If you didn&rsquo;t know better, you wouldn&rsquo;t even know the database existed. But it<br>does and Addrbook won&rsquo;t work without it.

The &ldquo;help&rdquo; message that is printed when you run Addrbook with no arguments<br>explains how editing works in the form of a list:

Writes the database contents of the entry to a text file.

Opens the text file in your editor.

Imports the edited contact information back to the database.

After using this program daily for a couple months now, I am convinced that the<br>database + text file method not only works reliably, but is super flexible. You<br>get plain text input and output in the Unix fashion, while retaining the full<br>power and reliability of a proper industrial-grade database (SQLite).

Backing up your contact data

One of the problems with storing information in a binary format (even a very<br>good one like SQLite) is that it&rsquo;s hard to track it with standard source<br>control tools.

When you use Addrbook, the text files are retained after they have been used,<br>which means that the database and text files are always 100% in sync with each<br>other.

(The only reason this would not be true is if there was an error in Addrbook or<br>your computer crashed while you were editing an entry. Or you tricked it, but<br>that&rsquo;s on you.)

Therefore, it is completely reasonable to put the txt directory<br>under standard textual version control to keep track of changes<br>to your contact data.

Version control plus a standard automated backup system (you do have<br>a backup system, right?) should be quite good protection against<br>mistakes and equipment failures.

Configuration

First, to run addrbook at all, you&rsquo;ll need to install the sqlite3 gem:

gem install sqlite3

There is no installer for Addrbook itself, so you&rsquo;ll need to prepare the<br>directories and database by hand (I made this tool for myself and I don&rsquo;t<br>need an installer):

mkdir ~/beans/addrbook<br>mkdir ~/beans/addrbook/txt

Create the addrbook.db database from the make_db.sql schema file. I like to<br>do this interactively in the sqlite3 shell to confirm everything is correct.

Example SQLite session (silently creates the required tables):

$ sqlite3 ~/beans/addrbook/addrbook.db<br>SQLite version 3.50.4 2025-07-30 19:33:53<br>sqlite> .read addrbook-repo/make_db.sql

While you&rsquo;re in there, verify the schema:

sqlite> .schema<br>CREATE TABLE contact (<br>contact_id INTEGER PRIMARY KEY,<br>name,<br>added,<br>notes<br>);<br>CREATE TABLE email ( contact_id INTEGER, email);<br>CREATE TABLE phone ( contact_id INTEGER, phone);<br>CREATE TABLE url ( contact_id INTEGER, url);<br>sqlite> .quit

Specify the path to the base directory in an environment variable like so:

ADDRBOOK_PATH=$HOME/beans/addrbook<br>export ADDRBOOK_PATH

Or you can hard-code your own path in the addrbook source like I did!<br>(See the source, near the top.)

Note: You can test addrbook with a temporary path like I often did<br>while developing, like so:

$ ADDRBOOK_PATH=/tmp/addr_test/ ./addrbook list

In summary, the address book directory should contain the following structure:

[dir]/addrbook.db - sqlite3 database, init with make_db.sql<br>[dir]/txt/ - empty directory, will store text files

The editor used to edit contacts is determined in the following order:

Environment variable $VISUAL

Or evironment variable $EDITOR

Or Vim

A viewer is determined likewise:

Environment variable $PAGER

Or less

The &lsquo;cat&rsquo; command is hard-coded to run whatever executable is named &lsquo;cat&rsquo;<br>on your system.

Aerc quickstart

I wrote Addrbook for use within the Aerc terminal email client.

I&rsquo;ve got this in ~/.config/aerc/binds.conf:

[view]<br># Address Book: av,ae,aa = "Address View, Edit, Add"<br>av = :term addrbook view '{{(index .From 0).Address}}' '{{(index .From...