mac-contacts
CLI for reading and managing macOS Contacts (CNContactStore). Supports searching by name, email, phone number, city, or country; showing all fields for a contact including list membership; creating and updating contacts with name, org, phone, email, and postal address; deleting contacts; and managing group (list) membership. Use when asked to look up, add, edit, remove, or organise contacts on macOS, or when you need a contact's phone number, email, address, or which lists they belong to.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/bdwelle/mac-contactsmac-contacts
macOS Contacts CLI backed by CNContactStore. All reads use unified contact
views (iCloud + local + Exchange merged). All writes are atomic via
CNSaveRequest. Group membership removal uses osascript to work around a
silent no-op in CNSaveRequest.removeMember_fromGroup_ for iCloud-backed
groups.
Dependencies
pip install pyobjc-framework-Contacts
pip install pyyaml
Grant Contacts access to Terminal (or your agent host) when prompted on first run, or via System Settings → Privacy & Security → Contacts.
Invocation
python3 skill://mac-contacts/scripts/mac-contacts.py <subcommand> [options]
All examples below use mac-contacts as shorthand for the full invocation.
Subcommands
search
Search contacts. With a positional query, performs a single-pass search across name, organisation, note, email, phone (digits normalised), and postal address fields. Use explicit flags to restrict to a specific field.
search [QUERY]
[--list LIST]
[--email EMAIL]
[--phone PHONE]
[--city CITY]
[--country COUNTRY]
| Flag | Description |
|---|---|
QUERY | Comprehensive search across all fields. Phone digits are matched fuzzily (query digits must appear in contact's digit-stripped number; minimum 4 digits required for phone matching). |
--list LIST | Return only contacts that are members of the named list/group. |
--email EMAIL | Match by email address (uses the CNContact native email predicate — efficient). |
--phone PHONE | Match by phone number; non-digit characters stripped before comparison. Minimum 4 digits. |
--city CITY | Match by city in any postal address. |
--country COUNTRY | Match by country in any postal address. |
Examples:
# Comprehensive — finds by name, org, email, phone, address
mac-contacts search "John"
mac-contacts search "[email protected]" # auto-matches email
mac-contacts search "415-555" # auto-matches phone (≥4 digits)
mac-contacts search "San Francisco" # auto-matches city
# Explicit field targeting
mac-contacts search --email "[email protected]"
mac-contacts search --phone "415" # error: fewer than 4 digits
mac-contacts search --phone "4155551234"
mac-contacts search --city "London"
mac-contacts search --country "Germany"
# Filter to list members
mac-contacts search --list "Work"
Output per contact: name, organisation, phone(s), email(s), address(es).
show
Show every available field for a contact, including list membership.
show NAME
Output includes: full name (with prefix/middle/suffix), nickname, organisation, job title, department, phones, emails, postal addresses, URLs, social profiles, birthday, dates, note (if readable), and Lists.
mac-contacts show "Jane Doe"
mac-contacts show "Apple" # matches any contact whose name contains "Apple"
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-bdwelle-mac-contacts": {
"enabled": true,
"auto_update": true
}
}
}