Caldav Calendar

Search

khal search "meeting"
khal search "dentist" --format "{start-date} {title}"

Create Events

khal new 2026-01-15 10:00 11:00 "Meeting title"
khal new 2026-01-15 "All day event"
khal new tomorrow 14:00 15:30 "Call" -a Work
khal new 2026-01-15 10:00 11:00 "With notes" :: Description goes here

After creating, sync to push changes:

vdirsyncer sync

Edit Events (interactive)

khal edit is interactive — requires a TTY. Use tmux if automating:

khal edit "search term"
khal edit -a CalendarName "search term"
khal edit --show-past "old event"

Menu options:

• s → edit summary
• d → edit description
• t → edit datetime range
• l → edit location
• D → delete event
• n → skip (save changes, next match)
• q → quit

After editing, sync:

vdirsyncer sync

Delete Events

Use khal edit, then press D to delete.

⚠️ Overnight Events (khal Gotcha)

Problem: khal new with overnight times (e.g., 10pm-2am) creates broken all-day events.

Solution: Write ICS files directly for overnight/multi-day timed events:

cat > /tmp/event.ics << 'EOF'
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Clawdbot//Calendar//EN
BEGIN:VEVENT
UID:unique-id-$(date +%s)@clawdbot
DTSTAMP:20260101T000000Z
DTSTART;TZID=America/New_York:20260211T220000
DTEND;TZID=America/New_York:20260212T020000
SUMMARY:Event Title
LOCATION:Location
DESCRIPTION:Description
END:VEVENT
END:VCALENDAR
EOF
cp /tmp/event.ics ~/.local/share/vdirsyncer/calendars/Clawdbot-Calendar/
vdirsyncer sync clawdbot_calendar

For same-day events: khal new works fine.

Output Formats

For scripting:

khal list --format "{start-date} {start-time}-{end-time} {title}" today 7d
khal list --format "{uid} | {title} | {calendar}" today

Placeholders: {title}, {description}, {start}, {end}, {start-date}, {start-time}, {end-date}, {end-time}, {location}, {calendar}, {uid}

Caching

khal caches events in ~/.local/share/khal/khal.db. If data looks stale after syncing:

rm ~/.local/share/khal/khal.db

Initial Setup

1. Configure vdirsyncer (~/.config/vdirsyncer/config)

Example for iCloud:

[general]
status_path = "~/.local/share/vdirsyncer/status/"

[pair icloud_calendar]
a = "icloud_remote"
b = "icloud_local"
collections = ["from a", "from b"]
conflict_resolution = "a wins"

[storage icloud_remote]
type = "caldav"
url = "https://caldav.icloud.com/"
username = "[email protected]"
password.fetch = ["command", "cat", "~/.config/vdirsyncer/icloud_password"]

[storage icloud_local]
type = "filesystem"
path = "~/.local/share/vdirsyncer/calendars/"
fileext = ".ics"

Provider URLs:

• iCloud: https://caldav.icloud.com/
• Google: Use google_calendar storage type
• Fastmail: https://caldav.fastmail.com/dav/calendars/user/EMAIL/
• Nextcloud: https://YOUR.CLOUD/remote.php/dav/calendars/USERNAME/

2. Configure khal (~/.config/khal/config)

[calendars]
[[my_calendars]]
path = ~/.local/share/vdirsyncer/calendars/*
type = discover

[default]
default_calendar = Home
highlight_event_days = True

[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d

3. Discover and sync

vdirsyncer discover   # First time only
vdirsyncer sync