81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
---
|
|
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.
|