Nextcloud Calendar

Nextcloud Calendar Management

Problem

Need to create, query, or manage calendar events in the user's Nextcloud calendar.

Context / Trigger Conditions

• User asks to create/add a calendar event
• User asks "what's on my calendar?" or similar
• User mentions scheduling something
• User says "remind me" with a date (create calendar event)
• Default calendar is always Nextcloud unless otherwise specified

Prerequisites

• Python 3 with caldav and icalendar packages available (installed via PYTHONPATH or system packages)
• Environment variables NEXTCLOUD_USER and NEXTCLOUD_APP_PASSWORD must be set

Solution

Script Location

.claude/calendar-query.py

Execution Pattern (CRITICAL)

Run the script directly with python3 (env vars are set in the environment):

python3 .claude/calendar-query.py [command] [options]

Available Commands

List Calendars

python .claude/calendar-query.py list

Query Events

# Today's events
python .claude/calendar-query.py today

# Tomorrow's events
python .claude/calendar-query.py tomorrow

# This week
python .claude/calendar-query.py week

# This month
python .claude/calendar-query.py month

# Custom date range
python .claude/calendar-query.py events --days 14
python .claude/calendar-query.py events --date 2026-04-10

# From specific calendar
python .claude/calendar-query.py today --calendar "Work"

Create Events

# All-day event (single day)
python .claude/calendar-query.py create --title "Doctor appointment" --start "2026-03-15" --all-day

# All-day event (multi-day) - end date is EXCLUSIVE
# For April 10-13, use end date April 14
python .claude/calendar-query.py create --title "Vacation" --start "2026-04-10" --end "2026-04-14" --all-day

# Timed event
python .claude/calendar-query.py create --title "Meeting" --start "2026-03-15 14:00" --end "2026-03-15 15:00"

# With location and description
python .claude/calendar-query.py create --title "Lunch" --start "tomorrow 12:00" --location "Cafe" --description "Team lunch"

# Relative dates work
python .claude/calendar-query.py create --title "Call" --start "today 16:00"
python .claude/calendar-query.py create --title "Review" --start "tomorrow 10:00"

Output Formats

# JSON output (for parsing)
python .claude/calendar-query.py today --json

# Text output (default, human-readable)
python .claude/calendar-query.py week

Complete Example

To create an event "Team offsite" from March 20-22, 2026:

python3 .claude/calendar-query.py create --title "Team offsite" --start "2026-03-20" --end "2026-03-23" --all-day

Important Notes

1. End dates are exclusive for all-day events (CalDAV standard). To create an event spanning April 10-13, set end to April 14.

2. No delete/update commands - The script currently only supports create and query. To modify events, user must do it manually in Nextcloud.

3. Default calendar is "Personal" - use --calendar flag for others.

Verification

• For queries: Output shows formatted event list
• For creates: Output shows "Event created: [title]" with calendar name and start date
• Exit code 0 = success, 1 = error (check output for details)

Common Errors