# Google Calendar on boxd

> Google Calendar is a time management tool providing scheduling features, event reminders, and integration with email and other apps for streamlined organization.

- Page: https://boxd.sh/integrations/googlecalendar/
- CLI: `run googlecalendar` (49 commands, 25 marked common)
- SDK: `import { googlecalendar } from "@boxd/run"`; every parameter and response type is at `@boxd/run/googlecalendar`
- Triggers: 7
- Connect: `run auth googlecalendar` (Sign in with Google Calendar), or https://app.boxd.sh/integrations/detail/googlecalendar
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth googlecalendar      # once: prints a link to connect your account
run googlecalendar           # list its commands
run googlecalendar find-event
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { googlecalendar } from "@boxd/run";

const result = await googlecalendar.findEvent({});
console.log(result);

googlecalendar.on("google-calendar-event-created", async (event) => {
  // Event Created: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run googlecalendar.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run googlecalendar <command> --help` lists the optional ones. "common" marks what `run googlecalendar` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `acl-delete` ·common | `googlecalendar.aclDelete()` | `--calendar-id` `--rule-id` | 0 | Deletes an access control rule from a Google Calendar |
| `acl-get` ·common | `googlecalendar.aclGet()` | `--calendar-id` `--rule-id` | 0 | Retrieves a specific access control rule for a calendar |
| `acl-insert` ·common | `googlecalendar.aclInsert()` | `--calendar-id` `--role` `--scope` | 1 | Creates an access control rule for a calendar |
| `acl-list` | `googlecalendar.aclList()` | `--calendarId` | 4 | Retrieves the list of access control rules (ACLs) for a specified calendar, providing the necessary 'rule_id' values required for updating specific ACL rules |
| `acl-patch` | `googlecalendar.aclPatch()` | `--calendar-id` `--rule-id` | 3 | Updates an existing access control rule for a calendar using patch semantics (partial update) |
| `acl-update` | `googlecalendar.aclUpdate()` | `--calendar-id` `--role` `--rule-id` | 1 | Updates an access control rule for the specified calendar |
| `acl-watch` | `googlecalendar.aclWatch()` | `--address` `--calendarId` `--id` | 3 | Watch for changes to ACL resources |
| `batch-events` | `googlecalendar.batchEvents()` | `--operations` | 1 | Execute up to 1000 event mutations (create/patch/delete) in one Google Calendar HTTP batch request with per-item status/results |
| `calendar-list-delete` ·common | `googlecalendar.calendarListDelete()` | `--calendar-id` | 0 | Remove a calendar from the user's calendar list |
| `calendar-list-get` ·common | `googlecalendar.calendarListGet()` | `--calendarId` | 0 | Retrieves metadata for a SINGLE specific calendar from the user's calendar list by its calendar ID |
| `calendar-list-insert` ·common | `googlecalendar.calendarListInsert()` | `--id` | 9 | Inserts an existing calendar into the user's calendar list, making it visible in the UI |
| `calendar-list-patch` ·common | `googlecalendar.calendarListPatch()` | `--calendar-id` | 9 | Updates an existing calendar on the user's calendar list using patch semantics |
| `calendar-list-update` | `googlecalendar.calendarListUpdate()` | `--calendar-id` | 9 | Updates a calendar list entry's display/subscription settings (color, visibility, reminders, selection) for the authenticated user, does not modify the underlying calendar resource (title, timezone… |
| `calendar-list-watch` | `googlecalendar.calendarListWatch()` | `--address` `--id` `--type` | 3 | Watch for changes to CalendarList resources using push notifications |
| `calendars-delete` ·common | `googlecalendar.calendarsDelete()` | `--calendar-id` | 0 | Deletes a secondary calendar that you own or have delete permissions on |
| `calendars-update` ·common | `googlecalendar.calendarsUpdate()` | `--calendarId` `--summary` | 3 | Full PUT-style update that overwrites all calendar metadata fields; unspecified optional fields are cleared |
| `channels-stop` ·common | `googlecalendar.channelsStop()` | `--id` `--resourceId` | 1 | Stop watching resources through a notification channel |
| `clear-calendar` | `googlecalendar.clearCalendar()` | `--calendar-id` | 0 | Clears a primary calendar by deleting all events from it |
| `colors-get` | `googlecalendar.colorsGet()` | — | 0 | Returns the color definitions for calendars and events |
| `create-calendar` ·common | `googlecalendar.createCalendar()` | `--summary` | 3 | Creates a new secondary Google Calendar with the specified title and optional settings |
| `create-event` ·common | `googlecalendar.createEvent()` | `--start-datetime` | 24 | Create a Google Calendar event using start_datetime plus duration fields |
| `delete-event` ·common | `googlecalendar.deleteEvent()` | `--event-id` | 3 | Deletes a specified event by `event_id` from a Google Calendar (`calendar_id`); idempotent, a 404 for an already-deleted event is a no-op |
| `duplicate-calendar` ·common | `googlecalendar.duplicateCalendar()` | `--summary` | 0 | Creates a new, empty Google Calendar with the specified title (summary) |
| `events-get` ·common | `googlecalendar.eventsGet()` | `--event-id` | 3 | Retrieves a SINGLE event by its unique event_id (REQUIRED) |
| `events-import` | `googlecalendar.eventsImport()` | `--end` `--iCalUID` `--start` | 20 | Import an event as a private copy to a calendar |
| `events-instances` ·common | `googlecalendar.eventsInstances()` | `--calendarId` `--eventId` | 8 | Returns instances of the specified recurring event |
| `events-list` | `googlecalendar.eventsList()` | — | 20 | Returns events on the specified calendar |
| `events-list-all-calendars` ·common | `googlecalendar.eventsListAllCalendars()` | `--time-max` `--time-min` | 7 | Return a unified event list across all calendars in the user's calendar list for a given time range |
| `events-move` | `googlecalendar.eventsMove()` | `--calendar-id` `--destination` `--event-id` | 1 | Moves an event to another calendar, i.e., changes an event's organizer |
| `events-watch` | `googlecalendar.eventsWatch()` | `--address` `--calendarId` `--id` | 4 | Watch for changes to Events resources |
| `find-event` ·common | `googlecalendar.findEvent()` | — | 11 | Finds events in a specified Google Calendar using text query, time ranges (event start/end, last modification), and event types |
| `find-free-slots` | `googlecalendar.findFreeSlots()` | — | 6 | Finds both free and busy time slots in Google Calendars for specified calendars within a defined time range |
| `free-busy-query` ·common ·deprecated | `googlecalendar.freeBusyQuery()` | `--items` `--timeMax` `--timeMin` | 3 | Use find-free-slots instead (though this tool provides wider secondary/shared calendar coverage) |
| `get-calendar` ·common | `googlecalendar.getCalendar()` | — | 1 | Retrieves a specific Google Calendar, identified by `calendar_id`, to which the authenticated user has access |
| `get-calendar-profile` ·common ·deprecated | `googlecalendar.getCalendarProfile()` | — | 0 | Use CalendarListGet instead |
| `get-current-date-time` | `googlecalendar.getCurrentDateTime()` | — | 1 | Gets the current date and time, allowing for a specific timezone offset |
| `list-buildings` | `googlecalendar.listBuildings()` | — | 3 | Lists all buildings for a Google Workspace customer account with full details including addresses, coordinates, and floor names |
| `list-calendar-resources` | `googlecalendar.listCalendarResources()` | — | 5 | Retrieves calendar resources (such as conference rooms) from a Google Workspace domain using the Admin SDK Directory API |
| `list-calendars` | `googlecalendar.listCalendars()` | — | 6 | Retrieves calendars from the user's Google Calendar list, with options for pagination and filtering |
| `list-settings` ·deprecated | `googlecalendar.listSettings()` | — | 2 | Use settings-list instead |
| `patch-calendar` ·common | `googlecalendar.patchCalendar()` | `--calendar-id` | 4 | Partially updates (PATCHes) an existing Google Calendar, modifying only the fields provided |
| `patch-event` ·common | `googlecalendar.patchEvent()` | `--calendar-id` `--event-id` | 31 | Update specified fields of an existing event in a Google Calendar using patch semantics (array fields like `attendees` are fully replaced if provided); ensure the `calendar_id` and `event_id` are… |
| `quick-add` | `googlecalendar.quickAdd()` | — | 3 | Parses natural language text to quickly create a basic Google Calendar event with its title, date, and time, suitable for simple scheduling; does not support direct attendee addition or recurring… |
| `remove-attendee` | `googlecalendar.removeAttendee()` | `--attendee-email` `--event-id` | 1 | Removes an attendee from a specified event in a Google Calendar; the calendar and event must exist |
| `settings-get` | `googlecalendar.settingsGet()` | `--setting` | 0 | Return a single user setting for the authenticated user |
| `settings-list` | `googlecalendar.settingsList()` | — | 3 | Returns all user settings for the authenticated user |
| `settings-watch` | `googlecalendar.settingsWatch()` | `--address` `--id` `--type` | 3 | Watch for changes to Settings resources |
| `sync-events` ·common ·deprecated | `googlecalendar.syncEvents()` | — | 6 | Use events-list instead |
| `update-event` ·common | `googlecalendar.updateEvent()` | `--event-id` `--start-datetime` | 23 | Updates an existing event in Google Calendar |

## Triggers

`googlecalendar.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"attendee-response-changed"` | Attendee Response Changed | — | Polling trigger that fires when any attendee's RSVP changes to accepted, declined, or tentative |
| `"event-canceled-deleted"` | Event Canceled or Deleted | — | Triggers when a Google Calendar event is cancelled or deleted |
| `"event-starting-soon"` | Event Starting Soon | — | Triggers when a calendar event is within a configured number of minutes from starting |
| `"google-calendar-event-change"` | Calendar Event Changes | — | SOON TO BE DEPRECATED - Use Calendar Event Sync (polling trigger) instead |
| `"google-calendar-event-created"` | Event Created | — | Polling trigger that fires when a new calendar event is created |
| `"google-calendar-event-sync"` | Calendar Event Sync | — | Polling trigger that returns full event data including details, attendees, and metadata |
| `"google-calendar-event-updated"` | Event Updated | — | Triggers when an existing Google Calendar event is modified |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.