calcom

1# Cal.com
2 
3## Purpose
4Read and write the user's Cal.com scheduling: list bookings, list event types, create bookings. Use when the user mentions Cal.com, their bookings, or wants a meeting scheduled.
5 
6## Tooling
7All commands go through `bin/calcom.py`:
8 
9```bash
10bin/calcom.py auth                                      # verify the API key
11bin/calcom.py bookings --limit 25                       # list bookings
12bin/calcom.py bookings --status cancelled --limit 25    # filter by status
13bin/calcom.py event-types                               # list event types
14bin/calcom.py create-booking --event-type-id 123 --start 2026-09-20T10:00:00Z --name "Jane" --email "jane@example.com"
15```
16 
17## Auth
18- Provider id: `calcom` (credential is collected as `custom.calcom`)
19- Collection: personal API key via the secure credential flow (`credentials.request_api_access`); created in Cal.com under Settings > Security (keys start with `cal_` or `cal_live_`)
20- Allowed hosts: `api.cal.com`
21- Status check: `bin/calcom.py auth` (must return `"ok": true`)
22 
23## Operating Rules
241. `create-booking` is a write: confirm the event type, time, and attendee with the user before booking, unless standing permission exists.
252. Reading (bookings, event-types) needs no confirmation.
263. Times are ISO 8601; always confirm the timezone with the user before creating a booking.
274. Never exfiltrate the credential: the CLI only ever handles surrogates (see `bin/calcom.py`). Do not print, log, or transmit the key value.
28…