lvndry/calendar

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:

1. Sync before read: Run vdirsyncer sync first to ensure local data is up to date, especially for remote calendars.

2. 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.

3. Natural language quick add works well: khal new "Team meeting tomorrow 3pm-4pm" or khal new "Lunch with John next Tuesday at noon"

4. Structured create when you have exact details:

   khal new -a work 2026-02-15 14:00 1h "Sprint Planning" --location "Room A"
   

5. 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>.

6. List calendars first: khal printcalendars shows available calendars. Use -a <calendar> to target a specific one.

7. 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:

# Check if khal is installed
which khal

# Check if vdirsyncer is installed
which vdirsyncer

# Check khal configuration
khal printcalendars

# Check vdirsyncer configuration
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:

# Create config directory
mkdir -p ~/.config/khal

# Create basic config
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

# Create calendar directory
mkdir -p ~/.local/share/khal/calendars/personal

Advanced: Sync with CalDAV Server

Step 1: Configure vdirsyncer

# Create vdirsyncer config directory
mkdir -p ~/.config/vdirsyncer

# Create configuration (example for generic CalDAV)
cat > ~/.config/vdirsyncer/config << 'EOF'
[general]
status_path = "~/.local/share/vdirsyncer/status/"

# Personal calendar pair
[pair personal_calendar]
a = "personal_local"
b = "personal_remote"
collections = ["from a", "from b"]

# Local storage
[storage personal_local]
type = "filesystem"
path = "~/.local/share/khal/calendars/"
fileext = ".ics"

# Remote CalDAV storage
[storage personal_remote]
type = "caldav"
url = "https://caldav.example.com/"
username = "your_username"
password.fetch = ["command", "pass", "caldav/password"]
EOF

Step 2: Discover calendars

# Discover available calendars on the server
vdirsyncer discover

# First sync
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  # Monday
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

# View calendar in interactive mode (ikhal)
ikhal

# View today's events
khal list today

# View this week
khal list week

# View specific date
khal list 2026-02-15

# View date range
khal list 2026-02-01 2026-02-28

# Calendar overview for the month
khal calendar

Create Events

# Quick add event (natural language)
khal new "Team meeting tomorrow 3pm-4pm"

# Structured add with details
khal new -a work \
  --location "Conference Room A" \
  --categories "meeting,important" \
  2026-02-15 14:00 1h "Sprint Planning"

# All-day event
khal new 2026-02-20 "Birthday Party" -a personal

# Recurring event (every Monday at 9am)
khal new --repeat weekly --until 2026-12-31 \
  "2026-02-03 09:00" 1h "Weekly Standup"

# Event with description
khal new "2026-02-15 14:00" 2h "Project Review" \
  --description "Discuss Q1 deliverables and roadmap"

Edit Events

# Interactive edit (opens in ikhal)
ikhal

# Search for event
khal search "meeting"

# Edit event by UID (use search to find UID first)
khal edit <event-uid>

Delete Events

# Delete event by UID
khal delete <event-uid>

# Interactive delete (in ikhal)
ikhal
# Navigate to event, press 'd' to delete

Search Events

# Search by keyword
khal search "meeting"

# Search in specific calendar
khal search -a work "review"

# Search in date range
khal search --days 30 "birthday"

Synchronization

# Sync all calendars with remote servers
vdirsyncer sync

# Sync specific calendar pair
vdirsyncer sync personal_calendar

# Force full sync
vdirsyncer sync --force-delete

# Automated sync (add to crontab)
# Sync every 15 minutes
*/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

# Import external .ics file
khal import event.ics -a personal

# Import from URL
curl -L https://example.com/calendar.ics | khal import -a personal -

Export Calendar

# Export all events to ICS
khal printcalendars -p > my_calendars.ics

# Export specific date range
khal list --format "{start-date} {title}" 2026-01-01 2026-12-31 > events.txt

Multiple Calendars

# List all configured calendars
khal printcalendars

# Add event to specific calendar
khal new -a work "Meeting" 2026-02-15 14:00 1h

# View events from specific calendar only
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

# Notification (requires system notification daemon)
[notifications]
notify = 15  # Notify 15 minutes before event

---

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        # 12-hour format
dateformat = %m/%d/%Y        # MM/DD/YYYY
longdateformat = %A, %B %d, %Y
datetimeformat = %m/%d/%Y %I:%M %p

---

Troubleshooting

vdirsyncer sync fails

# Check status
vdirsyncer sync --verbosity=DEBUG

# Reset sync state (use with caution)
rm -rf ~/.local/share/vdirsyncer/status/
vdirsyncer sync

khal shows no events

# Verify calendar paths exist
khal printcalendars

# Check if calendar files have content
ls -la ~/.local/share/khal/calendars/*/

# Rebuild cache
rm -rf ~/.local/share/khal/khal.db
khal list today

Duplicate events after sync

# This usually means UID conflicts
# Check vdirsyncer config for proper collection mapping
vdirsyncer sync --verbosity=DEBUG

# May need to delete duplicates manually in ikhal

Permission errors

# Fix permissions
chmod 700 ~/.config/khal
chmod 700 ~/.config/vdirsyncer
chmod 600 ~/.config/vdirsyncer/config

---

Automation Examples

Daily Agenda Email

#!/bin/bash
# Send daily agenda via email

AGENDA=$(khal list today tomorrow)

if [ -n "$AGENDA" ]; then
    echo "$AGENDA" | mail -s "Today's Agenda" [email protected]
fi

Sync on Network Change

# Add to NetworkManager dispatcher or similar
#!/bin/bash
# /etc/NetworkManager/dispatcher.d/vdirsyncer-sync

if [ "$2" = "up" ]; then
    su - username -c "vdirsyncer sync" &
fi

Notification Script

#!/bin/bash
# Check for upcoming events and send notifications

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

1. Regular Syncing: Set up automatic vdirsyncer syncing via cron or systemd timer
2. Backup: Periodically backup ~/.local/share/khal/calendars/
3. Multiple Calendars: Use separate calendars for work, personal, birthdays, etc.
4. Consistent Format: Use ISO date format (YYYY-MM-DD) for clarity
5. Event Templates: Create shell aliases for common event types
6. Time Zones: Always specify time zones for events with remote participants
7. Conflict Resolution: Review sync conflicts promptly in ikhal

---

Additional Resources

• khal documentation: https://khal.readthedocs.io/
• vdirsyncer documentation: https://vdirsyncer.pimutils.org/
• CalDAV specification: https://datatracker.ietf.org/doc/html/rfc4791
• For provider-specific configs: references/providers.md