Contacts

Orchard gives your AI client full read/write access to Apple Contacts, so lookups and edits happen without switching apps. Contacts is a Pro feature.

What you can do

“Find Jamie’s phone number and email address.”
“Add a new contact for Alex Rivera, works at Acme Inc as VP of Sales, mobile 555-0142.”
“Update Jamie’s contact with a new work email.”
“Show me the full details for the contact I just found.”
“Delete the duplicate ‘Test Contact’ entry.”

Available tools

Tool	Description
`contacts_search`	Search contacts by name, phone number, or email address.
`contacts_get_details`	Get full details for a specific contact by ID.
`contacts_create`	Create a new contact with name, organization, phone numbers, emails, and notes.
`contacts_update`	Update an existing contact’s fields.
`contacts_delete`	Delete a contact by ID.

contacts_search accepts a limit between 1 and 100 (default 20). Phone numbers and emails are arrays of {label, number} / {label, email} objects, so a contact can carry multiple entries of each.

Update replaces, it doesn't merge

contacts_update’s phone_numbers and email_addresses arrays replace the existing numbers and emails entirely; they aren’t merged. To add one new number, first call contacts_get_details for the existing entries, then pass the full list (existing plus new) back in the update.

Required permissions

Contacts needs the Contacts permission. macOS shows the authorization prompt the first time any contacts tool runs; unlike Reminders and Calendar, there’s no separate onboarding step.

macOS system permission dialog, shown here for Calendar; the Contacts prompt looks identical

CLI usage

The orchard contacts command exposes search, details, create, update, and delete.

orchard contacts search --query "Jamie" --limit 10

orchard contacts details --contact-id "ABC123-DEF456"

orchard contacts create --given-name "Alex" --family-name "Rivera" \
  --organization-name "Acme Inc" --job-title "VP of Sales" \
  --phone "mobile:555-0142" --email "work:alex@acme.example"

orchard contacts update --contact-id "ABC123-DEF456" --email "work:alex.rivera@acme.example"

orchard contacts delete --contact-id "ABC123-DEF456"

--phone and --email can be repeated to attach multiple numbers or addresses, formatted as label:value (for example --phone "home:555-0100" --phone "work:555-0199"). If you omit the label, --phone defaults to mobile and --email defaults to home.

Every subcommand accepts --json for machine-readable output. Run orchard contacts <subcommand> --help for the full flag list, or orchard help contacts <subcommand> for the same information. See the CLI Reference.

Tips & limitations

contacts_search matches against name, phone number, and email in a single query, so you don’t need separate calls for each field.
If you don’t know a contact’s ID, call contacts_search first: each result shows the contact’s ID inline ([ID: ...]), which you then pass as contact_id to details, update, and delete.
contacts_delete is immediate and has no undo from Orchard, so double-check the contact ID before deleting.