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"}'.