google_calendar
Google Calendar
Everything runs through hatch_gws_cli calendar .... Raw API calls are space-separated (<resource> <method>) and take a --params JSON object, plus a --json body when creating or editing. A timed event's start/end is a dateTime in RFC3339 with a timezone offset, like 2026-04-16T14:00:00-07:00; an all-day event uses a date-only date like 2026-04-16 instead (never mix the two on one event). Run hatch_gws_cli calendar <command> --help for a command's flags, and hatch_gws_cli schema calendar.events.insert (and so on) for a raw method's --params and --json shape before you use one you are unsure of.
Connecting
Calendar needs a one-time connect before commands return data. Run hatch_gws_cli calendar status. If it comes back not connected and returns a connect_url, post it as [Connect Google Calendar](<connect_url>), then stop and wait for the user to tap it. If no URL is returned, report that connection is unavailable and stop; never invent one. Connecting is the user's step: never open the sign-in, drive a browser to it, send the user to Settings, or ask for credentials. If status is unavailable, say Google Calendar is unavailable on this device and stop. Disconnect with hatch_gws_cli calendar disconnect. Post [Disconnect Google Calendar](<disconnect_url>) only when the command returns that URL; otherwise rerun status and report its state without inventing a link. If a later command fails with an auth error, missing connector, or not-connected status, rerun status: if not connected with a URL, post the connect link and wait; if connected, retry once; if unavailable or missing a URL, report that and stop. Auth flows only through status and disconnect. Never hand-author credential files or run raw gws auth.
If the user asks to add or link another Google Calendar account, run hatch_gws_cli calendar status and post the exact add_account_url it returns as [Add Google Calendar account](<add_account_url>). Never reuse connect_url for an additional account. If add_account_url is absent, say that adding another account is unavailable. To remove one specific Google Calendar account while keeping the others, direct the user to that account under Connectors in Settings; do not disconnect Google Calendar entirely.
More than one account
A user can link several Google accounts. Calendar service calls use the default account when --account is omitted, so most tasks need nothing extra and there is no need to list accounts first. When the user clearly means a specific one of several, list them with hatch_gws_cli calendar accounts (identity only, no tokens) and match their words to a display_name, then add --account <account_id> to the command. --account selects which linked account runs a calendar service call and which account a capability-aware status --for-command checks; plain status, disconnect, and accounts remain connector-wide lifecycle commands. If you cannot match the user's words to exactly one display_name, ask which account rather than guessing; a wrong or unlinked --account fails closed ("account may not be linked") — surface that and confirm the account, never silently retry on the default.
If Google returns 403, insufficientPermissions, or "insufficient authentication scopes," run hatch_gws_cli calendar status --for-command <command-or-method> with the same --account <account_id> selection as the failed operation. When scope_status is not_granted, post the returned scope_add_url exactly as [Additional Google Calendar access](<scope_add_url>) and tell the user to choose that same account on Google's consent screen. Do not substitute add_account_url: that starts a new-account flow rather than adding access to the selected account. Wait for consent to finish before retrying the command.