carddav-contacts

name	carddav-contacts
description	Sync and manage CardDAV contacts (Google, iCloud, Nextcloud, etc.) using vdirsyncer + khard.
metadata	{"clawdbot":{"emoji":"📇","os":["linux"],"requires":{"bins":["vdirsyncer","khard"]},"install":[{"id":"apt","kind":"apt","packages":["vdirsyncer","khard"],"bins":["vdirsyncer","khard"],"label":"Install vdirsyncer + khard via apt"}]}}

CardDAV Contacts (vdirsyncer + khard)

vdirsyncer syncs CardDAV contacts to local .vcf files. khard reads and manages them via CLI.

Sync First

Always sync before querying to ensure you have the latest contacts:

vdirsyncer sync

Quick Search (Smart)

If configured with default_action = list (standard), you can search directly without subcommands:

khard "john"                     # Search for "john" in all fields
khard "pilar"                    # Search for "pilar"

List & Search (Explicit)

Use list if you need specific flags or if the implicit search doesn't match your config.

khard list                       # List all contacts
khard list "john"                # Search explicitly
khard list -a work               # List only from 'work' address book
khard list -p                    # Parsable output (tab-separated)

View Contact Details

khard show "john doe"            # Show details (pretty print)
khard show --format yaml "john"  # Show as YAML (good for editing)

Quick Field Lookup

Extract specific info (great for piping):

khard email "john"               # List emails only
khard phone "john"               # List phone numbers only
khard postaddress "john"         # List postal addresses

Management

khard new                        # Create new contact (interactive editor)
khard edit "john"                # Edit contact (interactive editor)
khard remove "john"              # Delete contact
khard move "john" -a work        # Move to another address book

Configuration Setup

1. Configure vdirsyncer (~/.config/vdirsyncer/config)

[pair google_contacts]
a = "google_contacts_remote"
b = "google_contacts_local"
collections = ["from a", "from b"]
conflict_resolution = "a wins"

[storage google_contacts_remote]
type = "carddav"
url = "https://www.googleapis.com/.well-known/carddav"
username = "[e-mail]"
password.fetch = ["command", "cat", "~/.config/vdirsyncer/google_app_password"]

[storage google_contacts_local]
type = "filesystem"
path = "~/.local/share/vdirsyncer/contacts/"
fileext = ".vcf"

2. Configure khard (~/.config/khard/khard.conf)

Critically, set default_action = list to enable quick search.

[addressbooks]
[[google]]
path = ~/.local/share/vdirsyncer/contacts/default/

[general]
default_action = list
editor = vim
merge_editor = vimdiff

[contact table]
display = formatted_name
sort = last_name

3. Initialize

mkdir -p ~/.local/share/vdirsyncer/contacts
vdirsyncer discover google_contacts
vdirsyncer sync