> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Calendar

> Virtualize Google Calendar calendars and events as JSON files.

![](https://mintcdn.com/struktoai/F9Lv_nTaj6By6crk/images/python-logo.svg?fit=max\&auto=format\&n=F9Lv_nTaj6By6crk\&q=85\&s=cf5b268d330f7db46ea5cf6083f309a1)

Node.js

Browser

![](https://mintcdn.com/struktoai/CsxMCKUyfoQQJYHB/images/cloudflare-logo.svg?fit=max\&auto=format\&n=CsxMCKUyfoQQJYHB\&q=85\&s=23668457afa14abb3b0db0f5b9c0541a)

Every calendar the account can see becomes a folder of days, with one JSON
file per event.

## Setup

Turn on the Google Calendar API and get an OAuth client and refresh token, as
in [Google Workspace Setup](https://docs.mirage.strukto.ai/home/setup/google.md). Then export them:

```bash theme={null}
export GOOGLE_CLIENT_ID=...
export GOOGLE_CLIENT_SECRET=...
export GOOGLE_REFRESH_TOKEN=...
```

## Connect

> [tab] YAML
>
> ```yaml workspace.yaml theme={null}
> mounts:
>   /gcal:
>     vfs: gcal
>     mode: read
>     config:
>       client_id: ${GOOGLE_CLIENT_ID}
>       client_secret: ${GOOGLE_CLIENT_SECRET}
>       refresh_token: ${GOOGLE_REFRESH_TOKEN}
> ```
>
> ```bash theme={null}
> mirage workspace create workspace.yaml --id cal
> mirage shell -w cal -c 'ls /gcal'
> ```

> [tab] Python
>
> ```python theme={null}
> import os
>
> from mirage import MountMode, Workspace
> from mirage.vfs.gcal import GCalConfig, GCalVFS
>
> config = GCalConfig(
>     client_id=os.environ["GOOGLE_CLIENT_ID"],
>     client_secret=os.environ["GOOGLE_CLIENT_SECRET"],
>     refresh_token=os.environ["GOOGLE_REFRESH_TOKEN"],
> )
> ws = Workspace({"/gcal": GCalVFS(config)}, mode=MountMode.READ)
> result = await ws.shell("ls /gcal")
> print(await result.stdout_str())
> await ws.close()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { GCalVFS, MountMode, Workspace } from '@struktoai/mirage-node'
>
> const ws = new Workspace(
>   {
>     '/gcal': new GCalVFS({
>       clientId: process.env.GOOGLE_CLIENT_ID!,
>       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
>       refreshToken: process.env.GOOGLE_REFRESH_TOKEN!,
>     }),
>   },
>   { mode: MountMode.READ },
> )
> const result = await ws.shell('ls /gcal')
> console.log(result.stdoutText)
> await ws.close()
> ```

## Layout

```text theme={null}
/gcal/
  primary/
    calendar.json
    2026-11-16/
      7kq2m9__0900-0930_Team_Standup.gcal.json
  Engineering__team@group.calendar.google.com/
    2026-11-16/
      ...
```

* The primary calendar is `primary`; every other one ends in `__<calendar-id>`.
* One folder per day, back through history and 90 days ahead. `bucket_days: 7`
  or `30` makes 7- or 30-day folders.
* An event file holds the Calendar API's payload.

## Sample runs

```bash theme={null}
$ ls /gcal
Engineering__team@group.calendar.google.com
primary
```

```bash theme={null}
$ ls /gcal/primary/2026-11-16
7kq2m9__0900-0930_Team_Standup.gcal.json
p31xd0__1400-1500_Design_Review.gcal.json
```

```bash theme={null}
$ jq -r '.summary, .start.dateTime' /gcal/primary/2026-11-16/7kq2m9__0900-0930_Team_Standup.gcal.json
Team Standup
2026-11-16T09:00:00-08:00
```

On a `write` mount, `rm` an event file to delete the event for every attendee.
Create and edit events with the [`gws calendar`](https://docs.mirage.strukto.ai/home/setup/cli/gws) CLI.

## SDK guides

> [card] [Python](https://docs.mirage.strukto.ai/python/vfs/gcal.md)
>
> Every config field, the VFS.md and write support.

> [card] [TypeScript](https://docs.mirage.strukto.ai/typescript/vfs/gcal.md)
>
> Every config field, the VFS.md and write support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.