goobook

Allow goobook to access Google contacts using OAuth2

$ goobook authenticate

$ goobook dump_contacts

goobook [global_options] command [command_args]

Common commands:
goobook search [query]
goobook lookup contact_id
goobook add
goobook edit contact_id
goobook delete contact_id
goobook authorize
goobook clear-cache

search [query]
    Searches Google Contacts for entries matching the optional query (can be a string or regex).

lookup contact_id
    Displays detailed information for a specific contact identified by its unique contact_id.

add
    Interactively prompts the user to add a new contact to Google Contacts, opening an editor for details.

edit contact_id
    Interactively edits an existing contact identified by its contact_id, opening an editor to modify its fields.

delete contact_id
    Deletes a contact by its contact_id. Requires user confirmation before deletion.

authorize
    Initiates the OAuth2 authorization flow, opening a browser for you to grant goobook access to your Google Contacts.

clear-cache
    Clears the locally stored cache of Google Contacts, forcing a fresh download on the next operation.

import file
    Imports contacts from the specified file (e.g., vCard, CSV) into Google Contacts.

export file
    Exports all contacts from Google Contacts to the specified file (e.g., vCard, CSV).

help [command]
    Displays a help message for goobook in general, or for a specific command if provided.

-c FILE, --config-file=FILE
    Specifies an alternative path for the configuration file.

-s, --show-colors
    Forces the display of ANSI colors in the output, even if not automatically detected.

-n, --no-colors
    Disables the display of ANSI colors in the output.

-v, --verbose
    Shows more detailed output, primarily useful for debugging purposes.

-d, --debug
    Enables extensive debug messages for in-depth troubleshooting.

--no-cache
    Prevents the command from using or updating the local contact cache for the current operation.

-j, --json
    Outputs results in JSON format. Applicable to search and lookup commands.

-F FORMAT_STRING, --format=FORMAT_STRING
    Specifies a custom output format string for results. Applicable to search and lookup commands.

-e, --exact
    Performs an exact match search instead of a partial match. Applicable to the search command.

-f FIELDS, --fields=FIELDS
    Limits the fields displayed in search results to a comma-separated list of field names. Applicable to the search command.

-h, --help
    Shows a general help message and exits the program.

--version
    Displays the program's version number and exits.

goobook is a command-line tool that provides a powerful interface to Google Contacts. It enables users to search, add, edit, and delete contacts directly from the terminal, making it highly convenient for scripting or quick lookups. The tool securely syncs with your Google account, retrieving and managing contact information without requiring a web browser. It is particularly useful for integrating contact management into shell scripts, email clients like mutt, or other text-based workflows, offering a fast and efficient way to interact with your address book.

Requires an initial OAuth2 authorization process to grant goobook access to your Google Contacts.
Relies on the Google Contacts API, which may change and potentially affect functionality.
Interactive modes (e.g., add, edit) require a text editor to be configured via the EDITOR environment variable.
Full functionality depends on appropriate network connectivity to Google's services.

goobook stores its configuration and OAuth2 tokens (required for Google API access) in a user-specific configuration file, typically located at ~/.goobookrc. The authorization step, usually performed once via the authorize command, securely manages the API token, which is then cached locally.

To improve performance and reduce API calls, goobook maintains a local cache of your Google Contacts, often at ~/.goobook_cache.json. This cache allows for faster retrieval of contact information on subsequent queries. Users can clear this cache with the clear-cache command or bypass it for a specific operation using the --no-cache option.

goobook was developed by Carl Chenet as an open-source project to provide robust command-line interaction with Google Contacts. Its development began around 2013-2014, driven by the need for seamless integration of Google contact management into traditional Unix-like environments and text-based applications such as the mutt email client.

abook(1), mutt(1), khard(1), vdirsyncer(1)