> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Calendar
> Manage Google Calendar events through commands and Discord embeds.
ollim-bot provides full read/write access to one or more Google calendars.
You can list, show, add, update, and delete events through CLI commands,
and the agent can present events in Discord embeds with a delete button
for one-click removal.
By default, ollim-bot queries your **primary** calendar only. Configure
the `google_calendars` [runtime config key](/configuration/reference#runtime-configuration)
with a comma-separated list of calendar IDs to query multiple calendars
at once.
## Prerequisites
* Google account connected (see [Google integration setup](/getting-started/google-integration))
* Authenticated via [`/google-auth`](/core-usage/slash-commands#google-auth)
## Setup
No additional setup is required. Once you've completed the
[Google integration](/integrations/google-overview) setup, Calendar is ready to use.
## Usage
The `ollim-bot cal` subcommand provides seven operations.
### List today's events
```bash theme={null}
ollim-bot cal today
```
Shows events for the current day across every configured calendar. Each
line displays the event ID, date, time range, and title:
```text theme={null}
abc123def 2026-02-24 09:00-10:00 Team standup
ghi456jkl 2026-02-24 (all-day) Project deadline
```
When more than one calendar is configured, events from all calendars are
merged and sorted client-side, and each line is tagged with its source
calendar ID in brackets — for example `[primary]` or `[work@example.com]`.
Pass `--calendar ` to query a single calendar instead of all configured ones:
```bash theme={null}
ollim-bot cal today --calendar work@example.com
```
### List upcoming events
```bash theme={null}
ollim-bot cal upcoming
```
Shows events for the next 7 days by default. Use `--days` to change the window:
```bash theme={null}
ollim-bot cal upcoming --days 14
```
| Argument | Required | Default | Description |
| ------------ | -------- | -------------- | ---------------------------- |
| `--days` | No | `7` | Number of days to look ahead |
| `--calendar` | No | All configured | Calendar ID to query |
### Show event details
```bash theme={null}
ollim-bot cal show
```
Displays detailed information including title, time, location, description,
link, attendees (by email), status, and event ID.
Pass `--calendar ` when the event lives on a calendar other than the
first one you've configured. Defaults to the first entry of `google_calendars`.
### Add an event
```bash theme={null}
ollim-bot cal add "Team lunch" --start 2026-02-25T12:00 --end 2026-02-25T13:00 --description "At the Italian place"
```
| Argument | Required | Description |
| ---------------------- | -------- | ------------------------------------------------------- |
| `summary` (positional) | Yes | Event title |
| `--start` | Yes | Start time in `YYYY-MM-DDTHH:MM` format |
| `--end` | Yes | End time in `YYYY-MM-DDTHH:MM` format |
| `--description` | No | Event description |
| `--calendar` | No | Calendar ID — defaults to the first configured calendar |
Times without a timezone are treated as the configured timezone (`OLLIM_TIMEZONE`).
### Update an event
```bash theme={null}
ollim-bot cal update --summary "Updated title" --start 2026-02-25T13:00 --end 2026-02-25T14:00
```
At least one of `--summary`, `--start`, `--end`, or `--description` must
be provided. `--calendar ` targets a specific calendar; otherwise the
first configured calendar is used.
### Delete an event
```bash theme={null}
ollim-bot cal delete
```
Permanently deletes the event. Pass `--calendar ` when the event lives
on a calendar other than the first configured one.
### List available calendars
```bash theme={null}
ollim-bot cal calendars
```
Lists every calendar your Google account can access, showing the calendar
ID and its display name:
```text theme={null}
primary My Calendar
work@example.com Work
family12345@group.calendar.google.com Family
```
Use this output to pick IDs for the `google_calendars` config key.
The agent interacts with Google Calendar in two ways.
### Embed buttons
When the agent presents calendar events in a Discord embed, it can attach
a **Delete** button that permanently removes the event.
Clicking the button shows a temporary confirmation only you can see,
and the agent is informed of what you did so it stays in sync. Delete
buttons encode the source calendar ID so events on non-primary calendars
are removed from the correct calendar.
### CLI delegation
The agent can also run calendar commands directly for
operations like listing upcoming events, showing details, adding new events,
or updating existing entries. When you mention a specific calendar, the
agent passes `--calendar ` — otherwise it uses the configured defaults.
## Configuring which calendars to query
Calendar selection is controlled by the `google_calendars` runtime config
key. It accepts a comma-separated list of calendar IDs — defaults to
`primary`.
| Value | Behavior |
| --------------------------------------- | ---------------------------------------------------------------- |
| `primary` (default) | Queries only your primary calendar |
| `primary,work@example.com` | Queries both calendars; events are merged and sorted client-side |
| `family12345@group.calendar.google.com` | Queries that one calendar |
For write operations (`add`, `update`, `delete`, `show`), the **first**
entry in `google_calendars` is used when `--calendar` is not provided.
Run `ollim-bot cal calendars` to discover the IDs available on your
account. See the [configuration reference](/configuration/reference#runtime-configuration)
for how to inspect and change runtime config keys.
A 404 on an individual calendar (typo, revoked access) is logged as
`(calendar '' not found — skipped)` and the command continues with
the remaining calendars.
One function is exported from `google/calendar.py` for use by the button handler in `views.py`:
| Function | Signature | Returns |
| -------------- | ------------------------------------------------------------------ | ------------- |
| `delete_event` | `delete_event(event_id: str, calendar_id: str = "primary") -> str` | Event summary |
This is called via `asyncio.to_thread` in the button handler to avoid
blocking the event loop. The button's action string encodes the calendar
ID as `event_del:/` — the legacy
`event_del:` form (no calendar ID) still works and defaults to
`primary` for backward compatibility.
## Troubleshooting
Your Google connection may have expired or been revoked. The bot
detects this automatically and prompts you to reconnect — run
`/google-auth` to re-authenticate.
Event IDs are displayed as the first column in `ollim-bot cal today` and
`ollim-bot cal upcoming` output. When using embed buttons, the agent
handles this automatically.
Run `ollim-bot cal calendars` to list every calendar your Google account
can access, with its ID and display name. The ID is what you pass to
`--calendar` and to the `google_calendars` config key.
All times are handled in the configured timezone (`OLLIM_TIMEZONE`,
defaults to auto-detected system timezone with a UTC fallback). Times
you enter without a timezone are assumed to be in this timezone.
## Next steps
Manage your task list through similar CLI and agent interactions.
Shared OAuth setup and all available Google services.
How the agent builds Discord embeds with action buttons.
Full reference for all ollim-bot CLI subcommands.