Merge

openclaw/workspace/nextcloud-calendar/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: nextcloud-calendar
+description: Manage Nextcloud calendars via CalDAV. Provides a unified CLI for listing, searching, adding, updating, and deleting events.
+---
+
+# Nextcloud Calendar Skill
+
+All-in-one CalDAV management for Nextcloud. Uses environment variables for configuration.
+
+## Prerequisites
+
+Set these environment variables for your Nextcloud instance:
+
+- `NEXTCLOUD_URL` — Base URL (e.g., `https://tower.scarif.space`)
+- `NEXTCLOUD_USER` — Username (e.g., `chris`)
+- `NEXTCLOUD_PASSWORD` — App password (Settings → Security → Devices & Sessions)
+- `CALDAV_PRINCIPAL` — Principal path (e.g., `/remote.php/dav/principals/users/chris/`)
+
+You can copy `.env.example` to `.env` and fill it out if using a local runner that loads dotenv.
+
+## Unified CLI
+
+All operations go through `scripts/ncal.py`:
+
+```bash
+cd /home/node/.openclaw/workspace/nextcloud-calendar/scripts
+python3 ncal.py <command> [options]
+```
+
+### Commands
+
+| Command | Description | Important Options |
+|---------|-------------|-------------------|
+| `list` | List available calendars | none |
+| `events` | View events (defaults to **Personal** calendar) | `--today`, `--date YYYY-MM-DD`, `--start`/`--end`, `--search <text>`, `--calendar <name>` |
+| `add` | Create event | `--summary`, `--start`, `--end`, `--recurrence`, `--description` |
+| `update` | Modify event | `--uid` OR `--summary` + `--date`, plus `--set-*` flags |
+| `delete` | Remove event | `--uid` OR `--summary` + `--date` |
+| `exception` | Create exception for recurring event | `--uid`, `--date` (instance date), `--start` (new time), `--end` (new time) |
+| `test` | Check config and connectivity | none |
+
+### Examples
+
+```bash
+# List calendars
+python3 ncal.py list
+
+# Today's events
+python3 ncal.py events --today
+
+# Events on a specific date
+python3 ncal.py events --date 2026-02-13
+
+# Search for events containing "tennis"
+python3 ncal.py events --search tennis
+
+# Add an event
+python3 ncal.py add --summary "Dentist" --start "2026-02-14 14:00:00" --end "2026-02-14 15:00:00"
+
+# Add recurring weekly event (Wednesdays 18:30-19:30)
+python3 ncal.py add --summary "Tennis Coaching" --start "2026-02-11 18:30:00" --end "2026-02-11 19:30:00" --recurrence "FREQ=WEEKLY;BYDAY=WE"
+
+# Update an event by UID
+python3 ncal.py update --uid <uid> --set-summary "New Title"
+
+# Delete by UID
+python3 ncal.py delete --uid <uid>
+
+# Create exception for recurring event (change Feb 18th instance to 13:00-14:00)
+python3 ncal.py exception --uid <uid> --date 2026-02-18 --start 13:00 --end 14:00
+```
+
+## Notes
+
+- **Default calendar**: If you don't specify `--calendar`, the command defaults to your **Personal** calendar.
+- **Timestamps**: Recurring events may show their original creation date rather than each occurrence—this is normal CalDAV behavior and doesn't affect functionality.
+- Times are local (no timezone conversion performed). Use consistent times in your calendar's timezone.
+- Recurrence rules follow iCalendar RRULE format.
+- The script does not use any third-party Python packages beyond the standard library.
+- For security, avoid hardcoding passwords; use environment variables or a `.env` file loaded by your shell.