Dbochman/gws-calendar

Google Calendar (gws)

Access Google Calendar via the gws CLI at /opt/homebrew/bin/gws. Credentials are AES-256-GCM encrypted at ~/.config/gws/.

Read references/gws-cli.md before selecting an account, changing authentication, or executing a write.

Accounts

| Account | Owner | Service-command selection | |---------|-------|---------------------------| | ${DYLAN_EMAIL} | Dylan | GOOGLE_WORKSPACE_CLI_ACCOUNT=${DYLAN_EMAIL} | | ${JULIA_EMAIL} | Julia | GOOGLE_WORKSPACE_CLI_ACCOUNT=${JULIA_EMAIL} | | ${STARMARKET_GMAIL} | Dylan (spam) | GOOGLE_WORKSPACE_CLI_ACCOUNT=${STARMARKET_GMAIL} | | ${OPENCLAW_EMAIL} | OpenClaw | GOOGLE_WORKSPACE_CLI_ACCOUNT=${OPENCLAW_EMAIL} |

When Dylan asks about "my calendar", use default. When he says "Julia's calendar", use her account.

Command Pattern

All raw API commands follow: GOOGLE_WORKSPACE_CLI_ACCOUNT=<email> gws calendar <resource> <method> [--params '<JSON>'] [--json '<JSON>']

• --params = URL/query parameters (calendarId, timeMin, maxResults, etc.)
• --json = request body (for create/update)
• Omit the environment prefix for Dylan's default account.

List Calendars

gws calendar calendarList list

List Events

# Today's events
gws calendar events list --params '{
  "calendarId": "primary",
  "timeMin": "2026-03-05T00:00:00-05:00",
  "timeMax": "2026-03-06T00:00:00-05:00",
  "singleEvents": true,
  "orderBy": "startTime"
}'

# Next 7 days
gws calendar events list --params '{
  "calendarId": "primary",
  "timeMin": "2026-03-05T00:00:00-05:00",
  "timeMax": "2026-03-12T00:00:00-05:00",
  "singleEvents": true,
  "orderBy": "startTime"
}'

# Julia's events today
GOOGLE_WORKSPACE_CLI_ACCOUNT=${JULIA_EMAIL} gws calendar events list --params '{
  "calendarId": "primary",
  "timeMin": "2026-03-05T00:00:00-05:00",
  "timeMax": "2026-03-06T00:00:00-05:00",
  "singleEvents": true,
  "orderBy": "startTime"
}'

# All calendars (use calendarList first, then query each)
gws calendar events list --params '{
  "calendarId": "<calendarId>",
  "timeMin": "...",
  "timeMax": "...",
  "singleEvents": true,
  "orderBy": "startTime"
}'

Important: Always compute timeMin/timeMax as RFC3339 timestamps with timezone. Use America/New_York (-05:00 EST / -04:00 EDT).

Get a Single Event

gws calendar events get --params '{
  "calendarId": "primary",
  "eventId": "<eventId>"
}'

Search Events

Use the q parameter:

gws calendar events list --params '{
  "calendarId": "primary",
  "q": "dinner",
  "timeMin": "2026-03-01T00:00:00-05:00",
  "timeMax": "2026-03-31T00:00:00-05:00",
  "singleEvents": true,
  "orderBy": "startTime"
}'

Create an Event

gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Team Standup",
  "description": "Daily sync",
  "location": "Zoom",
  "start": {"dateTime": "2026-03-10T09:00:00-05:00", "timeZone": "America/New_York"},
  "end": {"dateTime": "2026-03-10T09:30:00-05:00", "timeZone": "America/New_York"},
  "attendees": [
    {"email": "[email protected]"}
  ]
}'

All-day event

gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Vacation",
  "start": {"date": "2026-03-15"},
  "end": {"date": "2026-03-16"}
}'

Recurring event

gws calendar events insert --params '{"calendarId": "primary"}' --json '{
  "summary": "Weekly Standup",
  "start": {"dateTime": "2026-03-10T09:00:00-05:00", "timeZone": "America/New_York"},
  "end": {"dateTime": "2026-03-10T09:15:00-05:00", "timeZone": "America/New_York"},
  "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"]
}'

Common RRULE patterns

| Pattern | RRULE | |---------|-------| | Every Monday | RRULE:FREQ=WEEKLY;BYDAY=MO | | Every weekday | RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR | | Biweekly Tuesday | RRULE:FREQ=WEEKLY;INTERVAL=2;BYDAY=TU | | Daily | RRULE:FREQ=DAILY | | 1st of every month | RRULE:FREQ=MONTHLY;BYMONTHDAY=1 | | First Friday of every month | RRULE:FREQ=MONTHLY;BYDAY=1FR | | Weekly until end of year | RRULE:FREQ=WEEKLY;BYDAY=WE;UNTIL=20261231T235959Z |

With Google Meet

gws calendar events insert --params '{"calendarId": "primary", "conferenceDataVersion": 1}' --json '{
  "summary": "1:1 with Alice",
  "start": {"dateTime": "2026-03-10T14:00:00-05:00", "timeZone": "America/New_York"},
  "end": {"dateTime": "2026-03-10T14:30:00-05:00", "timeZone": "America/New_York"},
  "attendees": [{"email": "[email protected]"}],
  "conferenceData": {
    "createRequest": {"requestId": "meet-1", "conferenceSolutionKey": {"type": "hangoutsMeet"}}
  }
}'

Update an Event

gws calendar events patch --params '{
  "calendarId": "primary",
  "eventId": "<eventId>"
}' --json '{
  "summary": "New Title",
  "start": {"dateTime": "2026-03-10T10:00:00-05:00", "timeZone": "America/New_York"},
  "end": {"dateTime": "2026-03-10T10:30:00-05:00", "timeZone": "America/New_York"}
}'

Use patch (not update) to only change specified fields.

Delete an Event

gws calendar events delete --params '{
  "calendarId": "primary",
  "eventId": "<eventId>"
}'

Check Free/Busy

gws calendar freebusy query --json '{
  "timeMin": "2026-03-10T00:00:00-05:00",
  "timeMax": "2026-03-10T23:59:59-05:00",
  "items": [
    {"id": "${DYLAN_EMAIL}"},
    {"id": "${JULIA_EMAIL}"}
  ]
}'

Respond to an Invitation

First get the event, then patch the attendee status:

# Get the event to find your attendee entry
gws calendar events get --params '{"calendarId": "primary", "eventId": "<eventId>"}'

# Accept/decline by updating the event
gws calendar events patch --params '{
  "calendarId": "primary",
  "eventId": "<eventId>"
}' --json '{
  "attendees": [{"email": "${DYLAN_EMAIL}", "responseStatus": "accepted"}]
}'

API Schema

For any command, check available parameters:

gws schema calendar.events.list
gws schema calendar.events.insert

Notes

• Default account: ${DYLAN_EMAIL}
• Always confirm with Dylan before creating, updating, or deleting events
• When creating events on Julia's calendar, double-confirm since it affects her schedule
• Calendar ID primary = default calendar for the account
• Times must be RFC3339 with timezone (e.g., 2026-03-10T09:00:00-05:00)
• Use singleEvents: true + orderBy: startTime when listing to expand recurring events
• When the user says "weekly", "recurring", etc. -> use recurrence array with RRULE
• Always confirm recurrence pattern before creating
• For recurring event modifications, use the instance eventId (contains _ suffix) for single-instance changes
• gws outputs JSON by default — pipe through jq or parse directly