google_contacts

Google Contacts

Everything runs through hatch_gws_cli people <resource> <method> — resource and method as separate words, with parameters in a --params JSON object and, for creates and edits, a --json request body. The flows below give the exact command for each task, so start there; for a command's flags run hatch_gws_cli people <resource> <method> --help, and for a method's --params/--json shape run hatch_gws_cli schema people.people.searchContacts (and so on).

A contact's id is an opaque resourceName like people/c1234567890, and people/me is the connected account itself. Reads must name the fields they want: searches take a readMask, and get/connections list take a personFields mask (both a comma list like names,emailAddresses,phoneNumbers). Never invent a resourceName — carry the one a read returned straight through to the edit or delete.

Connecting

Contacts needs a one-time connect before commands return data. Run hatch_gws_cli people status. If it is not connected, post the exact connect_url it returns as [Connect Google Contacts](<connect_url>) and wait for the user to tap it. Don't invent a URL, send the user to Settings, or ask for credentials.

To disconnect, run hatch_gws_cli people disconnect and post its disconnect_url as [Disconnect Google Contacts](<disconnect_url>).

If a command reports an auth failure or not-connected, rerun status and follow the link it returns. If status is unavailable, say Google Contacts isn't available on this device and stop. Auth flows only through status and disconnect, with no hand-authored credential files or raw gws auth.

Common flows

Find a contact

• Look someone up by name or email: people people searchContacts --params '{"query":"alice","readMask":"names,emailAddresses,phoneNumbers","pageSize":10}'.
• Browse the whole address book: people people connections list --params '{"resourceName":"people/me","personFields":"names,emailAddresses,phoneNumbers","pageSize":50}'. Use this for "who's in my contacts" or to page through everyone.
• One person's full detail, once you have their resourceName: people people get --params '{"resourceName":"people/<id>","personFields":"names,emailAddresses,phoneNumbers"}'.

Add a contact

people people createContact --json '{"names":[{"givenName":"Alice","familyName":"Smith"}],"emailAddresses":[{"value":"alice@example.com"}],"phoneNumbers":[{"value":"+15551234567"}]}'. A name is enough; add emailAddresses and phoneNumbers when the user gives them.

Edit a contact

people people updateContact --params '{"resourceName":"people/<id>","updatePersonFields":"emailAddresses"}' --json '{"etag":"<etag>","emailAddresses":[<the full list with your change>]}'.

Delete a contact

people people deleteContact --params '{"resourceName":"people/<id>"}'.

Rules

• Contact creation, editing, and deletion may proceed from a clear, unambiguous user request without an additional confirmation. Resolve the exact person before editing or deleting.
• Read before you edit or delete: resolve the person with a search or browse first, use the exact resourceName (and etag) that read returned, and never act on a contact you did not find. For an edit, include the fields you are keeping so an update does not drop them.
• Talk to the user in plain language only. The commands and their JSON output are for you, not the user: keep them out of your replies — no command or flag (hatch_gws_cli, --params), no status word (not_connected, unavailable), no resourceName, and no API field (etag, page tokens) or raw JSON. A contact's own name, email, and phone number are what the user asked for, so keep those in your reply.
• Never print tokens, secrets, or credential material. Redact them if they appear in tool output.
• Read results add contact_source_updated_at with UTC and user-local forms when Google supplies a source update time. Birthdays remain calendar dates.

Limits

• Contact groups and labels, "other contacts" (addresses auto-saved from mail, not full contacts), and directory or domain people are not first-class flows here. If a task needs one, check its shape with hatch_gws_cli schema people.<resource>.<method> and confirm before any change, but there is no seeded, tested recipe for it.