| name | calendar |
| description | Manage calendars using khal CLI and vdirsyncer. Use when the user wants to view, create, edit, or delete calendar events, sync calendars with CalDAV servers, manage multiple calendars, or mentions "calendar", "event", "appointment", "meeting", "schedule", "CalDAV", "khal", "vdirsyncer". |
Calendar Management
Manage calendars using khal - a standards-based CLI calendar application, and vdirsyncer - a tool for synchronizing calendars with CalDAV servers.
Agent Usage (Power User Patterns)
When using this skill as an agent, run commands via execute_command. Prefer these patterns:
-
Sync before read: Run vdirsyncer sync first to ensure local data is up to date, especially for remote calendars.
-
Use khal list for human-readable output, or khal list --format "{start} {end} {title}" <date range> for parsing. For machine parsing, khal printcalendars -p exports ICS.
-
Natural language quick add works well: khal new "Team meeting tomorrow 3pm-4pm" or khal new "Lunch with John next Tuesday at noon"
-
Structured create when you have exact details:
khal new -a work 2026-02-15 14:00 1h "Sprint Planning" --location "Room A"
-
Find UID before edit/delete: khal search "meeting" or khal search --days 7 "project" returns UIDs. Use the UID with khal edit <uid> or khal delete <uid>.
-
List calendars first: khal printcalendars shows available calendars. Use -a <calendar> to target a specific one.
-
Date ranges: khal list today, khal list week, khal list 2026-02-01 2026-02-28, or khal list tomorrow
Prerequisites Check
Before any calendar operation, verify tools are installed and configured:
which khal
which vdirsyncer
khal printcalendars
vdirsyncer discover
If not installed → Guide through Installation
If no calendars → Guide through Calendar Setup
Installation
macOS (Homebrew)
brew install khal
brew install vdirsyncer
Arch Linux
pacman -S khal
pacman -S vdirsyncer
Debian/Ubuntu
apt install khal
apt install vdirsyncer
Nix
nix-env -i khal
nix-env -i vdirsyncer
FreeBSD
pkg install py-khal
pkg install py-vdirsyncer
pip (Any OS)
pip install khal
pip install vdirsyncer
Install Latest Version
pip install git+https://github.com/pimutils/khal
pip install git+https://github.com/pimutils/vdirsyncer
Calendar Setup
Quick Start: Local Calendar Only
Create a basic local calendar configuration:
mkdir -p ~/.config/khal
cat > ~/.config/khal/config << 'EOF'
[calendars]
[[personal]]
path = ~/.local/share/khal/calendars/personal
color = dark blue
[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d
longdateformat = %Y-%m-%d
datetimeformat = %Y-%m-%d %H:%M
longdatetimeformat = %Y-%m-%d %H:%M
EOF
mkdir -p ~/.local/share/khal/calendars/personal
Advanced: Sync with CalDAV Server
Step 1: Configure vdirsyncer
mkdir -p ~/.config/vdirsyncer
cat > ~/.config/vdirsyncer/config << 'EOF'
[general]
status_path = "~/.local/share/vdirsyncer/status/"
[pair personal_calendar]
a = "personal_local"
b = "personal_remote"
collections = ["from a", "from b"]
[storage personal_local]
type = "filesystem"
path = "~/.local/share/khal/calendars/"
fileext = ".ics"
[storage personal_remote]
type = "caldav"
url = "https://caldav.example.com/"
username = "your_username"
password.fetch = ["command", "pass", "caldav/password"]
EOF
Step 2: Discover calendars
vdirsyncer discover
vdirsyncer sync
Step 3: Configure khal to use synced calendars
cat > ~/.config/khal/config << 'EOF'
[calendars]
[[personal]]
path = ~/.local/share/khal/calendars/personal
color = dark blue
priority = 20
[[work]]
path = ~/.local/share/khal/calendars/work
color = dark red
priority = 10
[locale]
timeformat = %H:%M
dateformat = %Y-%m-%d
longdateformat = %Y-%m-%d
datetimeformat = %Y-%m-%d %H:%M
longdatetimeformat = %Y-%m-%d %H:%M
firstweekday = 0
weeknumbers = right
[default]
default_calendar = personal
EOF
Provider-Specific Setup
| Provider | CalDAV URL | Notes |
|---|
| Google Calendar | https://apidata.googleusercontent.com/caldav/v2/ | Requires App Password or OAuth 2.0 |
| Nextcloud | https://nextcloud.example.com/remote.php/dav/ | Standard username/password |
| iCloud | https://caldav.icloud.com/ | Requires app-specific password |
| Fastmail | https://caldav.fastmail.com/dav/calendars/user/ | Standard username/password |
| Radicale | http://localhost:5232/ | Self-hosted, standard auth |
💡 Tip: Most providers use the same app-specific password for both email and calendar. Store credentials in pass with consistent naming (e.g., google/app-password, icloud/app-password) to reuse them across both email and calendar skills. For multiple accounts, use a hierarchical structure (e.g., google/personal/app-password, google/work/app-password)—the / creates folders to keep things organized.
For detailed provider configurations, see references/providers.md
Common Operations
View Calendar
ikhal
khal list today
khal list week
khal list 2026-02-15
khal list 2026-02-01 2026-02-28
khal calendar
Create Events
khal new "Team meeting tomorrow 3pm-4pm"
khal new -a work \
--location "Conference Room A" \
--categories "meeting,important" \
2026-02-15 14:00 1h "Sprint Planning"
khal new 2026-02-20 "Birthday Party" -a personal
khal new --repeat weekly --until 2026-12-31 \
"2026-02-03 09:00" 1h "Weekly Standup"
khal new "2026-02-15 14:00" 2h "Project Review" \
--description "Discuss Q1 deliverables and roadmap"
Edit Events
ikhal
khal search "meeting"
khal edit <event-uid>
Delete Events
khal delete <event-uid>
ikhal
Search Events
khal search "meeting"
khal search -a work "review"
khal search --days 30 "birthday"
Synchronization
vdirsyncer sync
vdirsyncer sync personal_calendar
vdirsyncer sync --force-delete
*/15 * * * * vdirsyncer sync >/dev/null 2>&1
Interactive Calendar (ikhal)
ikhal is the interactive TUI for browsing and editing calendars.
Launch
ikhal
Keyboard Shortcuts
| Key | Action |
|---|
n | Create new event |
e | Edit selected event |
d | Delete selected event |
t | Jump to today |
/ | Search events |
↑↓←→ | Navigate calendar |
Enter | View event details |
Tab | Switch between panes |
q | Quit |
Advanced Workflows
Import ICS Files
khal import event.ics -a personal
curl -L https://example.com/calendar.ics | khal import -a personal -
Export Calendar
khal printcalendars -p > my_calendars.ics
khal list --format "{start-date} {title}" 2026-01-01 2026-12-31 > events.txt
Multiple Calendars
khal printcalendars
khal new -a work "Meeting" 2026-02-15 14:00 1h
khal list -a personal today
Event Reminders
Configure desktop notifications by adding to khal config:
[default]
default_event_duration = 1h
default_dayevent_duration = 1d
[view]
event_view_always_visible = True
[notifications]
notify = 15
Configuration Tips
Time Zones
Handle multiple time zones in ~/.config/khal/config:
[locale]
local_timezone = America/New_York
default_timezone = America/New_York
Calendar Colors
Customize calendar colors for better visibility:
[calendars]
[[work]]
path = ~/.local/share/khal/calendars/work
color = dark red
priority = 10
[[personal]]
path = ~/.local/share/khal/calendars/personal
color = dark blue
priority = 20
[[birthdays]]
path = ~/.local/share/khal/calendars/birthdays
color = dark green
readonly = true
Date Formats
Customize date/time display:
[locale]
timeformat = %I:%M %p
dateformat = %m/%d/%Y
longdateformat = %A, %B %d, %Y
datetimeformat = %m/%d/%Y %I:%M %p
Troubleshooting
vdirsyncer sync fails
vdirsyncer sync --verbosity=DEBUG
rm -rf ~/.local/share/vdirsyncer/status/
vdirsyncer sync
khal shows no events
khal printcalendars
ls -la ~/.local/share/khal/calendars/*/
rm -rf ~/.local/share/khal/khal.db
khal list today
Duplicate events after sync
vdirsyncer sync --verbosity=DEBUG
Permission errors
chmod 700 ~/.config/khal
chmod 700 ~/.config/vdirsyncer
chmod 600 ~/.config/vdirsyncer/config
Automation Examples
Daily Agenda Email
#!/bin/bash
AGENDA=$(khal list today tomorrow)
if [ -n "$AGENDA" ]; then
echo "$AGENDA" | mail -s "Today's Agenda" user@example.com
fi
Sync on Network Change
if [ "$2" = "up" ]; then
su - username -c "vdirsyncer sync" &
fi
Notification Script
#!/bin/bash
EVENTS=$(khal list --format "{start-time} {title}" today | head -5)
if [ -n "$EVENTS" ]; then
notify-send "Upcoming Events" "$EVENTS"
fi
Integration with Other Tools
tmux Status Bar
Add to .tmux.conf:
set -g status-right '#(khal list today | head -1 | cut -c 1-40)'
Waybar/i3status
"custom/calendar": {
"exec": "khal list today | head -1",
"interval": 300,
"format": "📅 {}"
}
Best Practices
- Regular Syncing: Set up automatic vdirsyncer syncing via cron or systemd timer
- Backup: Periodically backup
~/.local/share/khal/calendars/
- Multiple Calendars: Use separate calendars for work, personal, birthdays, etc.
- Consistent Format: Use ISO date format (YYYY-MM-DD) for clarity
- Event Templates: Create shell aliases for common event types
- Time Zones: Always specify time zones for events with remote participants
- Conflict Resolution: Review sync conflicts promptly in ikhal
Additional Resources