Autocomplete Google contacts in Vim with Goobook
For many years I’ve been using mutt to read and send email. I stumbled across a post about how to hook up Vim and Goobook to autocomplete Google Contacts when composing email. The original Vim plugin called out to additional programs to transform Goobook output to the format appropriate for Vim autocompletion. Wanting to learn more about Vimscript I decided to port as much as possible over to native Vimscript. Read on to learn more about how to get this set up for yourself!
The first step is installing Goobook. Presuming you have a working Python install with Pip, simply run pip install --user goobook. This will install the goobook command to ~/.local/bin/goobook. Make sure goobook is on your path by adding ~/.local/bin to your path.
You’ll want to set up a dedicated Google Cloud project for use with Goobook. This is because Goobook requires access to the “People API” scope, which is considered a sensitive scope. Only a single OAuth consent screen can be created per project, and therefore any other OAuth clients in a project would be able to access the People API.
With this new project, configure a consent screen. The only values that are required are an app name, user support email, and developer contact information. Access to the “People API” is required, which is configured on the second page of the wizard. So long as you won’t be allowing anyone else to use your Goobook credentials, verification of the consent screen is not required. With the consent screen in place, follow the steps in the quickstart guide to enable the contacts API and create OAuth credentials.
With the client ID and secret generated for a desktop client as described in the quickstart guide, run goobook authenticate -- CLIENT_ID CLIENT_SECRET, replacing CLIENT_ID and CLIENT_SECRET with those generated by following the guide. Note that if you are running on a remote machine you may need to pass the --auth_host_port option (defaults to port 8080) and set up port forwarding, as only a browser which supports JavaScript can complete the OAuth flow. Previously it was possible to use the --noauth_local_webserver flag instead of port forwarding, but Google disabled the “Out-Of-Band” flow on October 3, 2022.
Because the OAuth consent screen has not been verified you will receive a warning that Google hasn’t verified this app. It’s okay – click Advanced, and then select “Go to … (unsafe)”. You’ll see a confirmation screen to access the contacts API. Click Allow and you’ll be redirected back to Goobook to complete the authentication flow. Note that you’ll likely get a couple of emails and a notification about sensitive access at this point, since Goobook can modify your contacts. Again, another reason to make sure you’ve got a dedicated project for running Goobook.
With authentication complete, you should be able to query Goobook. Try goobook query matt (or search for a name you have in your contacts.) You should see a table of results. If that works, great! If not, you’ll need to troubleshoot Goobook.
In order to enable autocompletion in Vim, you’ll want to add the following mailcomplete.vim to ~/.vim/autoload:
The original version of this script was written by Tom Davis. Above you’ll see that I replaced the usages of sed, cut and awk with native Vimscript as compared to the original version.
Finally, in order to enable this plugin when composing mail (based on filetype=mail), add the following to ~/.vim/ftplugin/mail.vim:
set omnifunc=mailcomplete#Complete
When composing mail in Vim (or when filetype=mail), you can now autocomplete Google contacts with omni completion. The default binding for omni completion is ^X^O. Start typing the name of a contact and then hit ^X^O. You should get a list of contacts and can use arrow keys to select!
Learning about Vimscript was a ton of fun, and the language is very full featured. Since I originally drafted this post the language has gotten more polished, and I easily ported over the last bit of this script (#Trim) this evening.
A great resource for learning and working with Vimscript is Learn Vimscript the Hard Way. And of course there’s the official documentation, which is excellent.