nextcloud-integration/skills/nextcloud-calendar/SKILL.md

Nextcloud Calendar Skill

Purpose: Manage calendars and events on Nextcloud servers using the nextcloud-calendar CLI tool.

Overview

This skill provides calendar operations for Nextcloud using the nextcloud-calendar Go binary. The CLI tool handles all CalDAV operations and iCalendar parsing.

Prerequisites

• Go compiler (for building the CLI tool)
• Nextcloud server URL
• Nextcloud username
• Nextcloud password (for app token retrieval)
• Calendar app enabled on Nextcloud

Bootstrap Process

This skill will automatically build all three Nextcloud CLI tools with your app token and then immediately forget all credentials.

Step 1: The skill will ask for:

• Nextcloud server URL (e.g., https://teamworkapps.com)
• Nextcloud username (e.g., wltbagent@shortcutsolutions.net)
• Nextcloud password (your normal login credentials, not app token)

Step 2: The skill will:

1. Authenticate to Nextcloud using your username and password
2. Retrieve or generate an app token from Nextcloud settings
3. Build all three CLI tools (files, contacts, calendar) with the app token
4. Verify that all three binaries were created
5. Immediately forget all credentials (never stored permanently)

Step 3: You're ready!

• Use any tool without passing credentials (app token is embedded at compile time)
• Example: nextcloud-list-calendars (no --url, --user, --token needed)
• Example: nextcloud-create-event --summary "Meeting" --start "2026-02-12T10:00:00Z" --end "2026-02-12T11:00:00Z"

Security Note:

• All credentials (username, password, and app token) are only used during the bootstrap process
• App token is retrieved automatically - you don't need to find it manually
• Credentials are never stored permanently - not in any file or environment variable
• The app token is embedded in the compiled binaries, which stay on your local system only
• Do not distribute built binaries outside your trusted environment

Flow: Normal credentials → Authenticate → Get App Token → Build All CLI Tools → Forget All Credentials → Ready to Use

Configuration

All credentials are embedded at compile time via Go ldflags. No runtime configuration needed.

Build-Time Configuration (Automatic)

The skill handles this automatically during bootstrap:

cd projects/nextcloud-integration/tools/go/nextcloud-calendar

go build -ldflags="-X 'main.BuildServerURL=https://teamworkapps.com' \
                 -X 'main.BuildUsername=wltbagent@shortcutsolutions.net' \
                 -X 'main.BuildToken=YOUR_APP_TOKEN'" \
  -o ~/bin/nextcloud-calendar .

Runtime Configuration (Fallback)

If not set at build time, the tool will check these environment variables:

export NEXTCLOUD_URL="https://cloud.example.com"
export NEXTCLOUD_USER="your-username"
export NEXTCLOUD_TOKEN="your-app-token"

Command-Line Flags (Override)

Pass credentials directly to each command using:

• --url
• --user
• --token

Priority: Build-time ldflags > Environment variables > Command-line flags

Tool Reference

All tools can be used without passing credentials (they're embedded at compile time).

nextcloud-list-calendars - List all calendars

# List all calendars
nextcloud-list-calendars

Output:

Calendars:
----------
Name: Personal
Path: personal
ETag: 

nextcloud-list-events - List events in a calendar

# List events in default calendar
nextcloud-list-events

# List events in specific calendar
nextcloud-list-events --calendar "work"

Output:

Events in 'personal' calendar:
-----------------
UID: 1770849610657274975
ETag: "18a633c6ae1ef474c2910a3bf9c12309"

nextcloud-get-event - Retrieve a specific event

# Get event by UID
nextcloud-get-event --uid "1770849610657274975"

Output:

Event: 1770849610657274975
--------
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//WLTBAgent//NextCalendar//EN
BEGIN:VEVENT
UID:1770849610657274975
DTSTAMP:20260211T221247Z
DTSTART:20260212T090000Z
DTEND:20260212T100000Z
SUMMARY:Meeting with Team
END:VEVENT
END:VCALENDAR

nextcloud-create-event - Create a new event

# Create event with summary and times (RFC3339 format)
nextcloud-create-event \
  --summary "Team Meeting" \
  --start "2026-02-12T10:00:00Z" \
  --end "2026-02-12T11:00:00Z"

# Create event from iCalendar file
nextcloud-create-event --ical /path/to/event.ics

Time Format: RFC3339 (UTC recommended)

• 2026-02-12T10:00:00Z - UTC with Z suffix
• 2026-02-12T10:00:00-07:00 - With timezone offset

Output:

Event created successfully

nextcloud-delete-event - Delete an event

# Delete event by UID
nextcloud-delete-event --uid "1770849610657274975"

Output:

Event deleted: 1770849610657274975

Use Cases

1. Event Management Workflow

# Create a new event
nextcloud-create-event \
  --summary "Project Review" \
  --start "2026-02-12T14:00:00Z" \
  --end "2026-02-12T15:00:00Z"

# Verify event was created
nextcloud-list-events | grep "Project"

# Retrieve event details
nextcloud-get-event --uid "$(nextcloud-list-events | grep 'Project' | awk '{print $2}')"

2. Meeting Scheduling

# Schedule meeting
nextcloud-create-event \
  --summary "Weekly Team Standup" \
  --start "2026-02-12T09:00:00Z" \
  --end "2026-02-12T09:30:00Z"

# (Note: Recurring events require full iCalendar RRULE support - not yet implemented)

3. Event Search Workflow

# List all events
nextcloud-list-events

# Get detailed event info
nextcloud-get-event --uid "event-uid"

# Search by summary (parsing get-event output)
nextcloud-get-event --uid "uid" | grep "SUMMARY"

4. Event Cleanup

# List all events
nextcloud-list-events

# Delete specific event
nextcloud-delete-event --uid "old-event-uid"

# Verify deletion
nextcloud-list-events

5. Bulk Event Import

# Import events from iCalendar files
for icsfile in events/*.ics; do
  nextcloud-create-event --ical "$icsfile"
done

iCalendar Format

The CLI tool generates iCalendar 2.0 format events:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//WLTBAgent//NextCalendar//EN
BEGIN:VEVENT
UID:<timestamp-nanoseconds>
DTSTAMP:<creation-time>
DTSTART:<start-time>
DTEND:<end-time>
SUMMARY:<event-summary>
END:VEVENT
END:VCALENDAR

Time Formats:

• DTSTAMP: Creation time (UTC)
• DTSTART: Event start time (UTC)
• DTEND: Event end time (UTC)
• Format: YYYYMMDDTHHmmssZ (RFC3339 compatible)

Error Handling

The nextcloud-calendar binary provides clear error messages:

Error	Meaning	Action
Error: credentials not set at build time	Need to re-bootstrap	Re-run bootstrap process
Error: --uid is required for get-event operation	Missing UID	Provide event UID
Error: event summary is required	Missing summary	Provide --summary flag
Error parsing start time: xxx	Invalid time format	Use RFC3339 format (YYYY-MM-DDTHH:MM:SSZ)
unexpected status: 404	Event not found	Verify UID and calendar
unexpected status: 401	Unauthorized	Re-bootstrap (token expired)
get event failed with status: xxx	Read error	Check event exists

Best Practices

1. Use RFC3339 time format for start/end times (UTC with Z suffix)
2. Store UIDs when creating events for later retrieval
3. Verify operations by listing after create/delete
4. Use UTC times to avoid timezone confusion
5. Handle iCalendar format when importing from files
6. No runtime configuration - credentials are embedded at compile time

Dependencies

• ~/bin/nextcloud-calendar - Go binary for CalDAV operations
• No external XML parsing needed (handled by Go)
• iCalendar files use standard RFC 5545 format

Related Skills

• nextcloud-contacts - For linking contacts to events
• nextcloud-files - For storing event attachments

---

OpenClaw skill wrapper for nextcloud-calendar Go binary with automatic app token retrieval