> ## 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.

The Google Calendar VFS mounts every calendar the account can see as a
directory of date buckets, with one JSON file per event. It uses the same
OAuth credentials as the other Google mounts; enable the Google Calendar API
and its scope as described in [Google Workspace Setup](https://docs.mirage.strukto.ai/home/setup/google.md).

For SDK guides, see [Google Calendar (Python)](https://docs.mirage.strukto.ai/python/vfs/gcal.md) and [Google Calendar (TypeScript)](https://docs.mirage.strukto.ai/typescript/setup/gcal.md).

## Connect

> [tab] Python
>
> ```python theme={null}
> import asyncio
> import os
>
> from mirage import MountMode, Workspace
> from mirage.vfs.gcal import GCalConfig, GCalVFS
>
>
> async def main() -> None:
>     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/primary")
>     print(await result.stdout_str(), end="")
>     await ws.close()
>
>
> asyncio.run(main())
> ```

> [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!,
>     bucketDays: 1,
>   }),
> }, { mode: MountMode.READ })
> const result = await ws.shell('ls /gcal/primary')
> process.stdout.write(result.stdoutText)
> await ws.close()
> ```

> [tab] YAML
>
> ```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}
> ```

## Browse events

```text theme={null}
/gcal/
  primary/
    calendar.json
    <YYYY-MM-DD>/
      <event-id>__<HHMM-HHMM>_<title>.gcal.json
  <name>__<calendar-id>/
    ...
```

The primary calendar is always `primary`; every other calendar directory ends
in `__<calendar-id>`. Each date directory holds the events of one day by
default; set `bucket_days` to `7` or `30` for 7-day or 30-day buckets. Without
`start_time` or `end_time`, a calendar lists all of its history up to 90 days
after today.

Use `ls` and date globs such as `ls /gcal/primary/2026-11-*` to find events,
then `cat` or `jq` to read the Calendar API payload. On a mount in write mode,
`rm` an event file to delete that event for every attendee; that needs the
`owner` or `writer` role on its calendar. Create and edit events with the
[`gws calendar`](https://docs.mirage.strukto.ai/home/setup/cli/gws) CLI.


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