radicale

name

radicale

description

This skill should be used when managing calendars and contacts on a self-hosted Radicale CalDAV/CardDAV server. Use when the user asks to "list my calendar", "what's on my calendar this week", "show me my events", "when is my next event", "add to my calendar", "create an event", "schedule a meeting", "schedule an event", "delete an event", "cancel event", "remove event", "find a contact", "what's someone's email", "search my contacts", "look up [person] in contacts", "add a contact", "save contact", "save someone's phone number", or mentions Radicale, CalDAV, CardDAV, calendar events, or contact management operations.

Radicale CalDAV/CardDAV Management

Manage calendars (events) and contacts on a self-hosted Radicale server using CalDAV and CardDAV protocols.

Type: Read & Write (calendar events and contacts)

Purpose

This skill enables comprehensive calendar and contact management through a self-hosted Radicale server. It provides read and write access to:

• Calendars - List, view, create, update, and delete calendar events
• Contacts - List, search, create, update, and delete contacts in addressbooks

All operations use the Python caldav library which implements the CalDAV (RFC 4791) and CardDAV (RFC 6352) protocols.

Setup

Prerequisites

Install required Python libraries:

pip install caldav vobject icalendar

Script Permissions:

The Python script can be made executable (optional but recommended):

chmod +x skills/radicale/scripts/radicale-api.py

You can then run it directly:

./scripts/radicale-api.py --help

Or without executable permissions using Python:

python scripts/radicale-api.py --help

Credentials

Configure these values in plugin userConfig. The hook writes ${XDG_CONFIG_HOME:-~/.config}/lab-radicale/config.env with mode 600. ~/.lab/.env remains a fallback during migration:

RADICALE_URL="http://localhost:5232"
RADICALE_USERNAME="admin"
RADICALE_PASSWORD="password"

Security:

• Generated config and .env files are local-only (never commit credentials)
• Set permissions: chmod 600 ~/.lab/.env

Core Operations

All operations use the scripts/radicale-api.py wrapper script. Output is JSON format for easy parsing.

Calendar Operations

List Calendars

python scripts/radicale-api.py calendars list

Returns array of calendars with name, URL, and ID.

View Events

List events in a calendar within a date range:

python scripts/radicale-api.py events list \
  --calendar "Personal" \
  --start "2026-02-08" \
  --end "2026-02-15"

Parameters:

• --calendar (required) - Calendar name (case-sensitive)
• --start (optional) - Start date (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)
• --end (optional) - End date (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS)

Default behavior: If start/end not specified, uses current date + 7 days.

Returns array of events with UID, summary, description, location, start, end, and timestamps.

Create Event

python scripts/radicale-api.py events create \
  --calendar "Personal" \
  --title "Meeting" \
  --start "2026-02-10T14:00:00" \
  --end "2026-02-10T15:00:00" \
  --location "Conference Room" \
  --description "Team sync"

Required parameters:

• --calendar - Calendar name
• --title - Event title/summary
• --start - Start datetime (YYYY-MM-DDTHH:MM:SS)
• --end - End datetime (YYYY-MM-DDTHH:MM:SS)

Optional parameters:

• --location - Event location
• --description - Event description

Important: Use ISO 8601 datetime format (YYYY-MM-DDTHH:MM:SS). End must be after start.

Delete Event

python scripts/radicale-api.py events delete \
  --calendar "Personal" \
  --uid "event-uid-here"

Get UID from events list output.

Contact Operations

List Addressbooks

python scripts/radicale-api.py contacts addressbooks

Returns array of addressbooks with name, URL, and ID.

List Contacts

python scripts/radicale-api.py contacts list \
  --addressbook "Contacts"

Returns array of contacts with UID, name, email, and phone.

Search Contacts

python scripts/radicale-api.py contacts search \
  --addressbook "Contacts" \
  --query "David"

Search behavior: Case-insensitive substring match against name and email fields.

Create Contact

python scripts/radicale-api.py contacts create \
  --addressbook "Contacts" \
  --name "John Doe" \
  --email "[e-mail]" \
  --phone "[phone]"

Required parameter:

• --name - Contact full name

Optional parameters:

• --email - Email address
• --phone - Phone number

Delete Contact

python scripts/radicale-api.py contacts delete \
  --addressbook "Contacts" \
  --uid "contact-uid-here"

Get UID from contacts list or contacts search output.

Natural Language Translation

When users make natural language requests, translate them to script commands:

Calendar Examples

User: "What's my calendar look like this week?"

Action:

1. Calculate current week date range
2. Run: python scripts/radicale-api.py events list --calendar "Personal" --start "YYYY-MM-DD" --end "YYYY-MM-DD"
3. Present events in human-readable format

User: "Add to my calendar Billy Strings in Athens, GA 02/07/2026 7PM EST"

Action:

1. Parse: title="Billy Strings", location="Athens, GA", start="2026-02-07T19:00:00", end="2026-02-07T23:00:00" (assume 4hr concert)
2. Run: python scripts/radicale-api.py events create --calendar "Personal" --title "Billy Strings" --start "2026-02-07T19:00:00" --end "2026-02-07T23:00:00" --location "Athens, GA"
3. Confirm creation

Contact Examples

User: "What's David Ryan's work email?"

Action:

1. Run: python scripts/radicale-api.py contacts search --addressbook "Contacts" --query "David Ryan"
2. Extract email field from results
3. Present: "David Ryan's email is [e-mail]"

User: "Add John Doe to my contacts, email [e-mail]"

Action:

1. Run: python scripts/radicale-api.py contacts create --addressbook "Contacts" --name "John Doe" --email "[e-mail]"
2. Confirm creation

Decision Tree

When user mentions calendars or contacts:

1. Determine operation type:

   • Calendar query ("show", "list", "what's on") → Use events list
   • Calendar create ("add", "create event", "schedule") → Use events create
   • Calendar delete ("remove", "delete", "cancel") → Use events delete
   • Contact query ("find", "search", "what's", "who is") → Use contacts search
   • Contact create ("add contact", "save contact") → Use contacts create
   • Contact delete ("remove contact", "delete contact") → Use contacts delete

2. Identify target:

   • Calendar operations → Ask which calendar (default: "Personal")
   • Contact operations → Ask which addressbook (default: "Contacts")

3. Extract parameters:

   • For events: Parse title, location, date/time from natural language
   • For contacts: Parse name, email, phone from natural language

4. Execute command:

   • Run appropriate script command
   • Parse JSON output

5. Present results:

   • Format JSON as human-readable text
   • Include relevant details (event times, contact info)
   • Confirm successful operations

Date/Time Handling

Important considerations:

• All times are local to the Radicale server timezone
• Use ISO 8601 format for consistency: YYYY-MM-DDTHH:MM:SS
• When user specifies "7PM EST", convert to 24-hour local time
• For all-day events, use same date for start/end with different times
• Default event duration: 1 hour (if user doesn't specify end time)

Common translations:

• "this week" → Calculate Mon-Sun dates from current date
• "next week" → Calculate Mon-Sun dates for following week
• "today" → Current date
• "tomorrow" → Current date + 1 day
• "7PM" → "19:00:00"
• "noon" → "12:00:00"

Error Handling

All operations return JSON with status. Check for:

Connection errors:

• ERROR: .env file not found → Guide user to create .env file
• ERROR: Failed to connect to Radicale → Check Radicale is running, verify URL
• ERROR: Authentication failed → Verify credentials in .env

Resource errors:

• ERROR: Calendar 'X' not found → List available calendars with calendars list
• ERROR: Addressbook 'X' not found → List addressbooks with contacts addressbooks

Data errors:

• ValueError: Invalid isoformat string → Fix datetime format to ISO 8601
• End time before start time → Adjust end time to be after start

Notes

Read-Write Operations:

• All operations modify data on the Radicale server
• Event creation is immediate (no confirmation prompt)
• Contact creation is immediate (no confirmation prompt)
• Deletions are permanent (no undo)

Performance:

• Use date ranges for event queries to avoid loading all events
• Search contacts instead of listing all when looking for specific person
• Calendar/contact listing can be slow with large datasets

Limitations:

• No timezone support in current implementation (uses local time)
• No recurring event support yet
• Contact fields limited to name, email, phone (vCard supports more)
• No event reminders/alarms

Security:

• All credentials stored in .env file (gitignored)
• API script never logs credentials
• Connection uses HTTP basic auth (HTTPS recommended for production)

Reference

Bundled references (load as needed):

• references/caldav-library.md — Python caldav library guide (auth patterns, CalDAV/CardDAV operations, error handling)
• references/quick-reference.md — command examples with sample outputs
• references/troubleshooting.md — installation, connection, auth, and data errors

External:

• Radicale Documentation
• caldav Library Docs

Agent Tool Usage

Run this skill's scripts with the Bash tool directly:

python ./skills/radicale/scripts/radicale-api.py [args]