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