Apple Contacts

Search and view your Apple Contacts from the command line using the

apple-contacts

CLI. This skill provides fast, read-only access to your contacts using Apple's native Contacts Framework.

Key Features:

• Native framework: Uses Apple's Contacts Framework for direct, fast access
• Multi-criteria search: Filter by name, email, phone, organization, address, birthday
• vCard export: Export contacts in standard vCard format
• Group management: Browse and search contact groups
• JSON output: Machine-readable output for automation

Setup & Configuration

Installation

From source:

git clone https://github.com/fishfisher/apple-contacts.git
cd apple-contacts && swift build -c release
cp .build/release/apple-contacts /usr/local/bin/

Or download a binary from the releases page.

Verify installation:

apple-contacts --help

First Run: macOS will prompt for Contacts access permission on first use. Grant access to enable the CLI.

Requirements

• macOS 14.0 or later
• Swift 6.0 or later (for building from source)
• Contacts app permission

Quick Start

# List all contacts
apple-contacts list

# Search for a contact by name
apple-contacts search "John"

# Show full contact details
apple-contacts show "John Smith"

# Search by email
apple-contacts search --email "john@example.com"

# Search by phone number
apple-contacts search --phone "555-1234"

# Find contacts with birthdays this month
apple-contacts search --birthday-month 1

# List all contact groups
apple-contacts groups

# Export contact to vCard
apple-contacts export "John Smith"

Core Capabilities

1. List All Contacts

Display all contacts in your address book:

# List all contacts
apple-contacts list

# Limit results
apple-contacts list --limit 20

# Output as JSON
apple-contacts list --json

2. Search Contacts

Find contacts using various criteria. Multiple filters use AND logic.

# Search by name (partial match)
apple-contacts search "John"
apple-contacts search "Smith"

# Search by email
apple-contacts search --email "gmail.com"
apple-contacts search --email "john@example.com"

# Search by phone number
apple-contacts search --phone "555"
apple-contacts search --phone "+1-555-123-4567"

# Search by organization
apple-contacts search --org "Acme"
apple-contacts search --org "Apple"

# Search by address
apple-contacts search --address "San Francisco"
apple-contacts search --address "CA"

# Search any field
apple-contacts search --any "keyword"

# Combine filters (AND logic)
apple-contacts search "John" --org "Apple"
apple-contacts search --email "gmail.com" --address "New York"

# Limit results
apple-contacts search "John" --limit 5

# Output as JSON
apple-contacts search "John" --json

3. Show Contact Details

Display complete information for a specific contact:

# Show contact by name
apple-contacts show "John Smith"

# Output as JSON
apple-contacts show "John Smith" --json

Shows all available fields including:

• Full name and nickname
• Phone numbers (with labels)
• Email addresses (with labels)
• Physical addresses
• Organization and job title
• Birthday
• Social profiles
• URLs

4. Birthday Search

Find contacts with birthdays:

# Find contacts with birthday on specific date (MM-DD format)
apple-contacts search --birthday 01-15

# Find contacts with birthdays this month
apple-contacts search --birthday-month 1

# Find December birthdays
apple-contacts search --birthday-month 12

# Combine with other filters
apple-contacts search --birthday-month 6 --org "Family"

5. Contact Groups

Browse and work with contact groups:

# List all groups
apple-contacts groups

# Output as JSON
apple-contacts groups --json

6. Export to vCard

Export contacts in vCard format for sharing or backup:

# Export single contact
apple-contacts export "John Smith"

# Save to file
apple-contacts export "John Smith" > john-smith.vcf

Output Formats

Default (Human-Readable)

John Smith
  Email: john@example.com (work)
  Phone: +1-555-123-4567 (mobile)
  Organization: Acme Corp

JSON Output

Use

--json

flag for machine-readable output:

apple-contacts search "John" --json
apple-contacts show "John Smith" --json
apple-contacts list --json
apple-contacts groups --json

JSON output is useful for:

• Scripting and automation
• Integration with other tools
• Data processing pipelines

Common Workflows

Find a Contact's Phone Number

# Quick search
apple-contacts search "Jane"

# Or show full details
apple-contacts show "Jane Doe"

Find Work Colleagues

# Search by company
apple-contacts search --org "MyCompany"

# Search by work email domain
apple-contacts search --email "@mycompany.com"

Birthday Reminders

# Find this month's birthdays
apple-contacts search --birthday-month $(date +%m)

# Find today's birthdays
apple-contacts search --birthday $(date +%m-%d)

Lookup by Email

# Find who owns an email address
apple-contacts search --email "unknown@example.com"

Find Local Contacts

# Search by city
apple-contacts search --address "San Francisco"

# Search by state
apple-contacts search --address "California"

Export for Sharing

# Export contact to vCard file
apple-contacts export "John Smith" > ~/Desktop/john.vcf

# Share multiple contacts
for name in "John Smith" "Jane Doe"; do
  apple-contacts export "$name" >> ~/Desktop/contacts.vcf
done

Limitations

• Read-only: Cannot create, edit, or delete contacts (use Contacts.app for modifications)
• macOS only: Requires macOS 14.0 or later
• Notes field: Accessing contact notes requires special Apple entitlements (not available)
• Permission required: Must grant Contacts access on first run

Troubleshooting

"Contacts access denied" error

• Go to System Settings > Privacy & Security > Contacts
• Enable access for Terminal (or your terminal app)
• Restart the terminal

Contact not found

• Try a partial name:

  apple-contacts search "Jo"

  instead of "John Smith"
• Check spelling
• Use

  apple-contacts list

  to see all contacts

Permission prompt not appearing

• Run any command to trigger the prompt:

  apple-contacts list

• If still no prompt, manually enable in System Settings > Privacy & Security > Contacts

Empty results

• Ensure Contacts.app has contacts (check the app directly)
• Verify permissions are granted
• Try broader search terms

Resources

• apple-contacts GitHub
• Apple Contacts Framework Documentation