📅 CalDAV Event Pusher

This is a tool to automate bulk creation and updates of events on a CalDAV calendar server such as Radicale. You give it some JSON mapping an arbitrary unique ID to VEVENT keys and it'll update existing events on the server or create new events:

myevents.json:

{
  "myevent-1234": {
    "SUMMARY": "My Event 1234",
    "DTSTART": "20260216T104500Z",
    "DTEND": "20260216T121500Z"
  },
  "myevent-2345": {
    "SUMMARY": "My Event 2345",
    "LOCATION": "here and there",
    "DTSTART": "20260217T163000Z",
    "DTEND": "20260217T183000Z"
  }
}

credentials.sh:

export CALDAV_USER=myuser
export CALDAV_PASSWORD=mypassword
export CALDAV_SERVER=https://caldav.myserver.de

> source credentials.sh # source credentials environment variables (to not have password in shell history)
> caldav-event-pusher --calendar uas --eventsfile myevents.json --dry-run # first check changes, then remove the --dry-run
...
╭─────────────────────── ✨ New event 'myevent-1234' ───────────────────────╮
│  ➕                       UID    →  b19c122d-eead-4de7-8f69-a3ac34450e14  │
│  ➕                   SUMMARY    →  My Event 1234                         │
│  ➕                   DTSTART    →  2026-02-16T10:45:00+00:00             │
│  ➕                     DTEND    →  2026-02-16T12:15:00+00:00             │
│  ➕  X-CALDAV-EVENT-PUSHER-ID    →  myevent-1234                          │
│  ➕             LAST-MODIFIED    →  2026-02-16T14:50:35.214112+00:00      │
│  ➕                   DTSTAMP    →  2026-02-16T14:50:35.214112+00:00      │
╰───────────────────────────────────────────────────────────────────────────╯
╭─────────────────────── ✨ New event 'myevent-2345' ───────────────────────╮
│  ➕                       UID    →  9f29985c-7db1-47b2-bd21-0664349eba4b  │
│  ➕                   SUMMARY    →  My Event 2345                         │
│  ➕                  LOCATION    →  here and there                        │
│  ➕                   DTSTART    →  2026-02-17T16:30:00+00:00             │
│  ➕                     DTEND    →  2026-02-17T18:30:00+00:00             │
│  ➕  X-CALDAV-EVENT-PUSHER-ID    →  myevent-2345                          │
│  ➕             LAST-MODIFIED    →  2026-02-16T14:50:35.224139+00:00      │
│  ➕                   DTSTAMP    →  2026-02-16T14:50:35.224139+00:00      │
╰───────────────────────────────────────────────────────────────────────────╯
...

# If you uploaded, then change myevents.json, and rerun:
> caldav-event-pusher --calendar uas --eventsfile myevents.json --dry-run # first check changes, then remove the --dry-run
╭────────────── 📝 Changes to 'myevent-2345' ───────────────╮
│  📝  LOCATION  here and there  →  that location           │
│  📝   SUMMARY  My Event 2345   →  My specific Event 2345  │
╰───────────────────────────────────────────────────────────╯

# If you made a mess and want to delete all of those events, just append the --delete option (maybe try first with --dry-run 😉)
> caldav-event-pusher --calendar uas --eventsfile myevents.json --delete --dry-run # first check what it would delete, then remove the --dry-run
# INFO     🗑️  Would delete event ad627b29-25a9-4764-ade0-23fe38fbf86b 'My Event 1234' (skip due to --dry-run)
# INFO     🗑️  Would delete event 4b5a7af3-abcc-44ab-85e5-c44f4a239d67 'My Event 2345' (skip due to --dry-run)

⚠️ Caveats

Make sure your CalDAV server supports arbitrary X-... fields. Radicale does, but Horde doesn't for example. When yours doesn't you can use --id-key DESCRIPTION for example to use the standard DESCRIPTION field for the ID. Not that you won't be able to push the event description then. Blame your server.