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:
```bash
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:

```bash
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

```bash
# List all calendars
nextcloud-list-calendars
```

**Output:**
```
Calendars:
----------
Name: Personal
Path: personal
ETag: 
```

### `nextcloud-list-events` - List events in a calendar

```bash
# 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

```bash
# 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

```bash
# 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

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

**Output:**
```
Event deleted: 1770849610657274975
```

## Use Cases

### 1. Event Management Workflow

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```ics
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*