apple-contacts

Files (2)

• SKILL.md
• sqlite.md · references/

SKILL.md (first lines)

# Apple Contacts

Zero-install: two macOS built-ins cover everything, no third-party CLI.

| Path | Use for | Speed |
|------|---------|-------|
| `sqlite3` read of the AddressBook DB | bulk reads, exports, joins, JSON output | ~10 ms for ~1000 contacts |
| `osascript` (AppleScript → Contacts.app) | targeted lookups, ALL writes, vCards | ~1 s per call; looping all contacts takes ~1 min |
| pyobjc + Contacts framework (CNContacts) | bulk WRITES, or shielding from schema churn | ~0.9 s for ~1000 contacts |

**NEVER write to the SQLite DB** - it is Contacts.app's and iCloud sync's
private store; reads are safe (`mode=ro`), writes corrupt sync. All mutations
go through AppleScript.

## Permissions (TCC)

- AppleScript needs an Automation grant (calling app → Contacts); sqlite3
  needs Full Disk Access. Both must be granted on the invoking terminal.
- Error `-1743` or "unable to open database": System Settings → Privacy &
  Security → Automation (or Full Disk Access) for the terminal app.
- TCC prompts don't fire in embedded terminals (VS Code); trigger the grant
  once from Terminal.app.

## Bulk reads (sqlite3)

The root DB `~/Library/Application Support/AddressBook/AddressBook-v22.abcddb`
is nearly empty - real data lives in per-account DBs at
`Sources/<uuid>/AddressBook-v22.abcddb`. Query every source:

```bash
for db in ~/Library/Application\ Support/AddressBook/Sources/*/AddressBook-v22.abcddb; do
sqlite3 -json "file:$db?mode=ro" "
SELECT r.ZUNIQUEID AS id, r.ZFIRSTNAME AS first, r.ZLASTNAME AS last,
       r.ZMIDDLENAME AS middle, r.ZNICKNAME AS nick,
       r.ZORGANIZATION AS org, r.ZJOBTITLE AS title,
       CASE WHEN strftime('%Y', r.ZBIRTHDAY + 978307200, 'unixepoch', 'localtime') < '1900'
            THEN strftime('%m-%d', r.ZBIRTHDAY + 978307200, 'unixepoch', 'localtime')
            ELSE date(r.ZBIRTHDAY + 978307200, 'unixepoch', 'localtime') END AS birthday,
       (SELECT group_concat(ZFULLNUMBER, '; ') FROM ZABCDPHONENUMBER WHERE ZOWNER = r.Z_PK) AS phones,
       (SELECT group_concat(ZADDRESS, '; ')    FROM ZABCDEMAILADDRESS WHERE ZOWNER = r.Z_PK) AS emails
FROM ZABCDRECORD r
WHERE r.ZFIRSTNAME IS NOT NULL OR r.ZLASTNAME IS NOT NULL OR r.ZORGANIZATION IS NOT NULL;"
done
```

`ZUNIQUEID` is the same `UUID:ABPerson` id AppleScript uses - the stable
cross-path key. Full schema, more columns (socials, URLs, notes, addresses),
and label decoding: [references/sqlite.md](references/sqlite.md).

## Targeted lookups (AppleScript)

```bash
# Count / list names
osascript -e 'tell application "Contacts" to get name of every person whose name contains "John"'

# Full details for one person (NEVER `first person whose` - buggy; filter then item 1)
osascript -e 'tell application "Contacts"
  set matches to every person whose name contains "John"
  if (count of matches) > 0 then
    set p to item 1 of matches
    return {id of p, name of p, value of phones of p, value of emails of p, organization of p}
  end if
end tell'

# By id (stable - prefer over names once known)
osascript -e 'tell application "Contacts" to get name of person id "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:ABPerson"'

# Single-contact vCard
osascript -e 'tell application "Contacts" to get vcard of person id "...:ABPerson"'
```

Phone search (`whose value of phones contains "..."`) is exact-match on the
stored format (`+1XXXXXXXXXX` ≠ `XXXXXXXXXX`) - for phone/email lookups use
the sqlite path with `LIKE` instead. Name `contains` is case-insensitive
partial; `is` is exact. No match returns empty output, not an error.

## Writes (AppleScript)

Every mutation needs an explicit `save` inside the `tell` block or it
silently doesn't persist. All verified working:

```bash
# Create
osascript -e 'tell application "Contacts"
  set p to make new person with properties {first name:"Jane", last name:"Doe", organization:"Acme"}
  make new phone at end of phones of p with properties {label:"mobile", value:"+15551234567"}
  make new email at end of emails of p with properties {label:"work", value:"jane@example.com"}
  save
  return id of p
end tell'

# Edit a property (birthday: build the date from components - literals are locale-fragile)
osascript -e 'tell application "Contacts"
  set d to current date
  set {year of d, month of d, day of d} to {1997, 4, 20}
  set birth date of person id "...:ABPerson" to d
  save
end tell'

# Delete
osascript -e 'tell application "Contacts"
  delete person id "...:ABPerson"
  save
end tell'
```

Labels: `mobile`, `home`, `work`, `main`, `other` (or custom strings).
Confirm with the user before deleting or bulk-editing real contacts.

## Gotchas

- Bulk `get vcard of every person` fails (error `-1741`, reply too large);
  per-person looping works but is slow. Bulk = sqlite.
- Long AppleScript ops need `with timeout of N seconds ... end timeout` (the
  default Apple-event timeout is 2 min, and osascript otherwise hangs).
- Birthday with no year is stored as year **1604** (Apple's no-year
  sentinel) - test `year < 1900` and emit MM-DD. (`ZBIRTHDAYYEARLESS` is not
  a flag: it's the MM-DD as a timestamp in year 2001, set for every birthday.)
- Raw labels in sqlite/vCards look like `_$!<Mobile>!$_` - strip to the inner

From alexjmiller5/agent-config-public, MIT.

More from alexjmiller5/agent-config-public