diegosouzapw 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 listto 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