Add Nextcloud integration tools
- CLI tools: nextcloud-client, nextcloud-contacts, nextcloud-calendar, nextcloud-mail - Build script with compile-time credentials - Skills for all four tools - Email tool supports IMAP/SMTP with attachment download
This commit is contained in:
WLTBAgent
303
skills/nextcloud-calendar/SKILL.md
Normal file
303
skills/nextcloud-calendar/SKILL.md
Normal file
@@ -0,0 +1,303 @@
|
||||
# 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*
|
||||
582
skills/nextcloud-capabilities/SKILL.md
Normal file
582
skills/nextcloud-capabilities/SKILL.md
Normal file
@@ -0,0 +1,582 @@
|
||||
# Nextcloud Capabilities Skill
|
||||
|
||||
**Purpose:** Query Nextcloud server capabilities, version, and available apps.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides access to the Nextcloud Capabilities API (OCS endpoint). Capabilities are useful for:
|
||||
- Detecting server version
|
||||
- Checking which apps are installed
|
||||
- Validating feature availability before using app-specific APIs
|
||||
- Theming information (colors, logos)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Nextcloud server URL
|
||||
- Username and app token
|
||||
- HTTPS connection
|
||||
- OCS API enabled on Nextcloud
|
||||
|
||||
## Configuration
|
||||
|
||||
Set these environment variables:
|
||||
|
||||
```bash
|
||||
export NEXTCLOUD_URL="https://cloud.example.com"
|
||||
export NEXTCLOUD_USER="your-username"
|
||||
export NEXTCLOUD_TOKEN="your-app-token"
|
||||
```
|
||||
|
||||
Or create `~/.config/nextcloud/config.json`:
|
||||
```json
|
||||
{
|
||||
"url": "https://cloud.example.com",
|
||||
"user": "your-username",
|
||||
"token": "your-app-token"
|
||||
}
|
||||
```
|
||||
|
||||
## Tool Reference
|
||||
|
||||
### `nextcloud-capabilities` - Get server capabilities
|
||||
|
||||
```bash
|
||||
# Get all capabilities
|
||||
nextcloud-capabilities
|
||||
|
||||
# Get specific capability section
|
||||
nextcloud-capabilities --section core
|
||||
nextcloud-capabilities --section theming
|
||||
nextcloud-capabilities --section files
|
||||
nextcloud-capabilities --section deck
|
||||
```
|
||||
|
||||
### `nextcloud-version` - Get server version
|
||||
|
||||
```bash
|
||||
# Get full version info
|
||||
nextcloud-version
|
||||
|
||||
# Get version only
|
||||
nextcloud-version --short
|
||||
```
|
||||
|
||||
### `nextcloud-apps` - List installed apps
|
||||
|
||||
```bash
|
||||
# List all apps
|
||||
nextcloud-apps
|
||||
|
||||
# Filter by enabled state
|
||||
nextcloud-apps --enabled
|
||||
|
||||
# Filter by name
|
||||
nextcloud-apps --search calendar
|
||||
```
|
||||
|
||||
### `nextcloud-theming` - Get theming information
|
||||
|
||||
```bash
|
||||
# Get all theming data
|
||||
nextcloud-theming
|
||||
|
||||
# Get color scheme only
|
||||
nextcloud-theming --colors
|
||||
```
|
||||
|
||||
### `nextcloud-quota` - Get user quota information
|
||||
|
||||
```bash
|
||||
# Get quota (if files app provides)
|
||||
nextcloud-quota
|
||||
```
|
||||
|
||||
## API Details
|
||||
|
||||
### Capabilities Endpoint
|
||||
|
||||
**URL:** `{NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities`
|
||||
|
||||
**Method:** GET
|
||||
|
||||
**Headers:**
|
||||
```
|
||||
OCS-APIRequest: true
|
||||
Accept: application/json
|
||||
Authorization: Basic {base64(user:token)}
|
||||
```
|
||||
|
||||
**Response Format:** OCS XML with JSON data inside:
|
||||
```xml
|
||||
<?xml version="1.0"?>
|
||||
<ocs>
|
||||
<meta>
|
||||
<status>ok</status>
|
||||
<statuscode>200</statuscode>
|
||||
<message>OK</message>
|
||||
</meta>
|
||||
<data>
|
||||
<!-- JSON data here -->
|
||||
</data>
|
||||
</ocs>
|
||||
```
|
||||
|
||||
## Capability Sections
|
||||
|
||||
### Core Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"core": {
|
||||
"pollinterval": 60,
|
||||
"webdav-root": "remote.php/webdav",
|
||||
"referenceapi": "https://github.com/nextcloud/server"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Theming Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"theming": {
|
||||
"name": "Nextcloud",
|
||||
"url": "https://nextcloud.com",
|
||||
"slogan": "A safe home for all your data",
|
||||
"color": "#0082c9",
|
||||
"color-text": "#ffffff",
|
||||
"color-element": "#0082c9",
|
||||
"color-element-bright": "#aaaaaa",
|
||||
"color-element-dark": "#555555",
|
||||
"logo": "https://cloud.example.com/index.php/apps/theming/logo?v=1",
|
||||
"background": "https://cloud.example.com/index.php/apps/theming/background?v=1",
|
||||
"background-plain": "",
|
||||
"background-default": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Files Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"files": {
|
||||
"versioning": true,
|
||||
"bigfilechunking": true,
|
||||
"undelete": true,
|
||||
"blacklisted_files": "",
|
||||
"direct_download": true,
|
||||
"direct_editing": true,
|
||||
"sharing": {
|
||||
"api_enabled": true,
|
||||
"public": {
|
||||
"enabled": true,
|
||||
"password": {
|
||||
"enforced": false,
|
||||
"enforced_for": {}
|
||||
},
|
||||
"expire_date": {
|
||||
"enabled": true,
|
||||
"enforced": false,
|
||||
"days": ""
|
||||
},
|
||||
"multiple": true,
|
||||
"upload": false
|
||||
},
|
||||
"resharing": {
|
||||
"enabled": true,
|
||||
"upload": true
|
||||
}
|
||||
},
|
||||
"federated_cloud_sharing": {
|
||||
"incoming": true,
|
||||
"outgoing": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Deck Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"deck": {
|
||||
"enabled": true,
|
||||
"version": "1.0.0",
|
||||
"board_limits": [],
|
||||
"max_upload_size": 10485760
|
||||
"can_create_boards": true,
|
||||
"can_manage": true
|
||||
"file_attachments": true,
|
||||
"comments": true,
|
||||
"labels": true
|
||||
"archived_board_support": false
|
||||
"archived_cards_support": false,
|
||||
"card_attachments": true,
|
||||
"acl_support": true,
|
||||
"acl_shares": true,
|
||||
"default_permission": {
|
||||
"PERMISSION_READ": true,
|
||||
"PERMISSION_EDIT": true,
|
||||
"PERMISSION_MANAGE": false,
|
||||
"PERMISSION_SHARE": false
|
||||
},
|
||||
"calendar": false
|
||||
"notifications": true
|
||||
"polling_interval": 60
|
||||
"version_history": [
|
||||
{
|
||||
"version": "1.0.0",
|
||||
"features": "board_limits, card_attachments, comments, labels"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Talk Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"spreed": {
|
||||
"enabled": true,
|
||||
"version": "19.0.0",
|
||||
"features": {
|
||||
"audio": true,
|
||||
"video": true,
|
||||
"chat": true,
|
||||
"guest-signaling": false,
|
||||
"rooms": {
|
||||
"allow_guests": false,
|
||||
"max_rooms": -1,
|
||||
"max_participants": -1
|
||||
},
|
||||
"recording": {
|
||||
"enabled": false,
|
||||
"group_only": false
|
||||
},
|
||||
"breakout_rooms": false,
|
||||
"webinar": false,
|
||||
"signaling": {
|
||||
"mode": "internal",
|
||||
"version": "2",
|
||||
"support": []
|
||||
}
|
||||
},
|
||||
"rich_object_list": true,
|
||||
"rich_object_config": false,
|
||||
"rich_object_list_share": true,
|
||||
"edit_messages": true,
|
||||
"federation": false,
|
||||
"voice": {
|
||||
"bridge": false
|
||||
},
|
||||
"notifications": {
|
||||
"version": "3",
|
||||
"notifications": true,
|
||||
"push": true,
|
||||
"sound": true
|
||||
},
|
||||
"expiration": {
|
||||
"enabled": false,
|
||||
"hours": ""
|
||||
},
|
||||
"circles": false,
|
||||
"mentions": false,
|
||||
"commands": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notifications Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"notifications": {
|
||||
"ocs-endpoints": {
|
||||
"list": "/ocs/v2.php/apps/notifications/api/v2/notifications",
|
||||
"get": "/ocs/v2.php/apps/notifications/api/v2/notifications/{id}",
|
||||
"delete": "/ocs/v2.php/apps/notifications/api/v2/notifications/{id}",
|
||||
"push": "/ocs/v2.php/apps/notifications/api/v2/push",
|
||||
"devices": "/ocs/v2.php/apps/notifications/api/v2/devices",
|
||||
"register": "/ocs/v2.php/apps/notifications/api/v2/devices",
|
||||
"delete-device": "/ocs/v2.php/apps/notifications/api/v2/devices/{id}"
|
||||
},
|
||||
"features": {
|
||||
"notifications": true,
|
||||
"push": false,
|
||||
"sound": "",
|
||||
"admin-notifications": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Calendar Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"calendar": {
|
||||
"installed": true,
|
||||
"version": "4.0.0",
|
||||
"features": {
|
||||
"birthday-calendar": false,
|
||||
"publishing": false,
|
||||
"rich-description": false,
|
||||
"alarm": true,
|
||||
"timezones": true,
|
||||
"caldav": true,
|
||||
"sharee": {
|
||||
"api_enabled": true
|
||||
},
|
||||
"webcal": {
|
||||
"enabled": false
|
||||
}
|
||||
},
|
||||
"versionhistory": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Contacts Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"dav": {
|
||||
"contacts": {
|
||||
"enabled": true,
|
||||
"version": "6.0.0",
|
||||
"features": {
|
||||
"photo": false,
|
||||
"circles": false,
|
||||
"addressbooks": true,
|
||||
"version": "6.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notes Capabilities
|
||||
|
||||
```json
|
||||
{
|
||||
"notes": {
|
||||
"installed": true,
|
||||
"version": "4.6.4",
|
||||
"features": {
|
||||
"version": "4.6.4",
|
||||
"api_version": "1.0",
|
||||
"files": false,
|
||||
"versioning": true,
|
||||
"markdown": false,
|
||||
"markdown_file_extension": "txt",
|
||||
"markdown_file_extension_is_customizable": false
|
||||
"description_max_length": null,
|
||||
"categories": false,
|
||||
"editable": true,
|
||||
"custom_properties": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
### Authentication
|
||||
|
||||
```bash
|
||||
curl -u ${NEXTCLOUD_USER}:${NEXTCLOUD_TOKEN} \
|
||||
-H "OCS-APIRequest: true" \
|
||||
-H "Accept: application/json" \
|
||||
${NEXTCLOUD_URL}/ocs/v1.php/cloud/capabilities
|
||||
```
|
||||
|
||||
### Example Request
|
||||
|
||||
```bash
|
||||
curl -u ${USER}:${TOKEN} \
|
||||
-H "OCS-APIRequest: true" \
|
||||
-H "Accept: application/json" \
|
||||
https://cloud.example.com/ocs/v1.php/cloud/capabilities
|
||||
```
|
||||
|
||||
### Example Response
|
||||
|
||||
```json
|
||||
{
|
||||
"ocs": {
|
||||
"meta": {
|
||||
"statuscode": 100,
|
||||
"status": "ok"
|
||||
},
|
||||
"data": {
|
||||
"version": {
|
||||
"major": 25,
|
||||
"minor": 0,
|
||||
"micro": "2",
|
||||
"string": "25.0.2",
|
||||
"edition": "",
|
||||
"extendedSupport": ""
|
||||
},
|
||||
"capabilities": {
|
||||
"core": { ... },
|
||||
"theming": { ... },
|
||||
"files": { ... },
|
||||
"deck": { ... },
|
||||
"spreed": { ... },
|
||||
"notifications": { ... },
|
||||
"calendar": { ... },
|
||||
"dav": { ... },
|
||||
"notes": { ... }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Validate Server Capabilities
|
||||
|
||||
```bash
|
||||
# Check if Deck is enabled
|
||||
if nextcloud-capabilities | jq -r '.capabilities.deck.enabled'; then
|
||||
echo "Deck is available"
|
||||
else
|
||||
echo "Deck not available"
|
||||
fi
|
||||
|
||||
# Check Deck version
|
||||
nextcloud-capabilities | jq -r '.capabilities.deck.version.string'
|
||||
```
|
||||
|
||||
### 2. Check API Version
|
||||
|
||||
```bash
|
||||
# Get version
|
||||
VERSION=$(nextcloud-version | jq -r '.capabilities.version.string')
|
||||
|
||||
# Check if minimum version is met
|
||||
if [ "$VERSION" \> "25.0.0" ]; then
|
||||
echo "Server meets minimum version requirement"
|
||||
else
|
||||
echo "Server too old"
|
||||
fi
|
||||
```
|
||||
|
||||
### 3. Validate Feature Support
|
||||
|
||||
```bash
|
||||
# Check if notifications push is enabled
|
||||
if nextcloud-capabilities | jq -r '.capabilities.notifications.features.push'; then
|
||||
echo "Push notifications supported"
|
||||
else
|
||||
echo "Push notifications not supported"
|
||||
fi
|
||||
|
||||
# Check if direct download is available
|
||||
if nextcloud-capabilities | jq -r '.capabilities.files.sharing.direct_download'; then
|
||||
echo "Direct download feature available"
|
||||
else
|
||||
echo "Direct download not available"
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. Get Theming Colors
|
||||
|
||||
```bash
|
||||
# Get color scheme
|
||||
nextcloud-theming
|
||||
|
||||
# Parse colors (example output)
|
||||
COLOR=$(echo "$THEMING" | jq -r '.theming.color')
|
||||
TEXT_COLOR=$(echo "$THEMING" | jq -r '.theming.color_text')
|
||||
|
||||
echo "Primary color: $COLOR"
|
||||
echo "Text color: $TEXT_COLOR"
|
||||
```
|
||||
|
||||
### 5. App Availability Check
|
||||
|
||||
```bash
|
||||
# Check which apps are installed
|
||||
APPS=$(nextcloud-apps)
|
||||
|
||||
echo "Installed apps:"
|
||||
echo "$APPS" | jq -r '.data.capabilities | keys'
|
||||
|
||||
# Check if specific app exists
|
||||
if echo "$APPS" | jq -r 'has("deck")'; then
|
||||
echo "Deck is installed"
|
||||
fi
|
||||
|
||||
if echo "$APPS" | jq -r 'has("calendar")'; then
|
||||
echo "Calendar is installed"
|
||||
fi
|
||||
|
||||
if echo "$APPS" | jq -r 'has("notes")'; then
|
||||
echo "Notes is installed"
|
||||
fi
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
| HTTP Status | Meaning | Action |
|
||||
|-------------|---------|--------|
|
||||
| 200 | Success | Parse capabilities XML/JSON |
|
||||
| 401 | Unauthorized | Check credentials |
|
||||
| 403 | Forbidden | Check permissions |
|
||||
| 404 | Not Found | API endpoint not available |
|
||||
| 500 | Server Error | Nextcloud server error |
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Test connection
|
||||
nextcloud-test --capabilities
|
||||
|
||||
# Test capabilities retrieval
|
||||
nextcloud-test --capabilities-get
|
||||
|
||||
# Test specific section
|
||||
nextcloud-test --capabilities --section deck
|
||||
|
||||
# Test all sections
|
||||
nextcloud-test --capabilities --all
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `curl` for HTTP requests
|
||||
- `jq` for JSON parsing (recommended)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Cache capabilities** - Capabilities rarely change, cache for 5-10 minutes
|
||||
2. **Validate before use** - Check if app is enabled before using app-specific APIs
|
||||
3. **Version compatibility** - Check server version before using features
|
||||
4. **Handle errors gracefully** - If capabilities endpoint returns error, assume minimal feature set
|
||||
5. **Theming** - Use theming colors to customize UI when applicable
|
||||
6. **Group Limits** - Check group_limit in Deck capabilities before creating boards
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Capabilities change detection
|
||||
- [ ] App installation/removal tracking
|
||||
- [ ] Feature compatibility matrix
|
||||
- [ ] Automatic API version adaptation
|
||||
- [ ] Server health check integration
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **nextcloud-files** - For file operations (capabilities will inform approach)
|
||||
- **nextcloud-deck** - For Kanban boards (check Deck capabilities first)
|
||||
- **nextcloud-talk** - For chat/calls (check Talk capabilities first)
|
||||
- **nextcloud-calendar** - For calendar events (check Calendar capabilities first)
|
||||
- **nextcloud-notes** - For notes (check Notes capabilities first)
|
||||
|
||||
---
|
||||
|
||||
*OCS API implementation for Nextcloud capabilities detection*
|
||||
299
skills/nextcloud-contacts/SKILL.md
Normal file
299
skills/nextcloud-contacts/SKILL.md
Normal file
@@ -0,0 +1,299 @@
|
||||
# Nextcloud Contacts Skill
|
||||
|
||||
**Purpose:** Manage contacts and address books on Nextcloud servers using the nextcloud-contacts CLI tool.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides contact operations for Nextcloud using the nextcloud-contacts Go binary. The CLI tool handles all CardDAV operations and vCard parsing.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Go compiler (for building CLI tool)
|
||||
- Nextcloud server URL
|
||||
- Nextcloud username
|
||||
- Nextcloud password (for app token retrieval)
|
||||
- Contacts 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)
|
||||
|
||||
**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 (username, password, and app token are never stored)
|
||||
|
||||
**Step 3: You're ready!**
|
||||
- Use any tool without passing credentials (app token is embedded at compile time)
|
||||
- Example: `nextcloud-list-books` (no --url, --user, --token needed)
|
||||
- Example: `nextcloud-create-contact --name "John" --email "john@example.com"`
|
||||
|
||||
**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** in any file or environment
|
||||
- **The app token is embedded** in the compiled binary at build time
|
||||
- **The compiled binary stays** on your local system only
|
||||
- **Do not distribute** built binaries outside your trusted environment
|
||||
|
||||
## Configuration
|
||||
|
||||
All credentials are embedded at compile time via Go ldflags. No runtime configuration needed.
|
||||
|
||||
### Build-Time Configuration (Automatic)
|
||||
|
||||
The skill will handle this automatically during bootstrap:
|
||||
```bash
|
||||
cd projects/nextcloud-integration/tools/go/nextcloud-contacts
|
||||
|
||||
go build -ldflags="-X 'main.BuildServerURL=https://teamworkapps.com' \
|
||||
-X 'main.BuildUsername=wltbagent@shortcutsolutions.net' \
|
||||
-X 'main.BuildToken=YOUR_APP_TOKEN'" \
|
||||
-o ~/bin/nextcloud-contacts .
|
||||
```
|
||||
|
||||
### 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 (Fallback)
|
||||
|
||||
Override credentials for specific commands using:
|
||||
- `--url`
|
||||
- `--user`
|
||||
- `--token`
|
||||
|
||||
**Priority:** Build-time ldflags > Environment variables > Command-line flags
|
||||
|
||||
## Tool Reference
|
||||
|
||||
All tools can be used without passing credentials.
|
||||
|
||||
### `nextcloud-list-books` - List all address books
|
||||
|
||||
```bash
|
||||
nextcloud-list-books
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# List all address books
|
||||
nextcloud-list-books
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Address Books:
|
||||
--------------
|
||||
Name: Contacts
|
||||
Path: contacts
|
||||
ETag:
|
||||
|
||||
Name: Recently contacted
|
||||
Path: z-app-generated--contactsinteraction--recent
|
||||
ETag:
|
||||
```
|
||||
|
||||
### `nextcloud-list-contacts` - List contacts in an address book
|
||||
|
||||
```bash
|
||||
# List contacts in default book
|
||||
nextcloud-list-contacts
|
||||
|
||||
# List contacts in specific book
|
||||
nextcloud-list-contacts --book "work-contacts"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# List contacts
|
||||
nextcloud-list-contacts
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Contacts in 'contacts':
|
||||
--------------
|
||||
UID: 1770849610657274975
|
||||
ETag: "037658b635c2523a8cf70085e81e4f69"
|
||||
```
|
||||
|
||||
### `nextcloud-get-contact` - Retrieve a specific contact
|
||||
|
||||
```bash
|
||||
# Get contact by UID
|
||||
nextcloud-get-contact --uid "1770849610657274975"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Get contact
|
||||
nextcloud-get-contact --uid "contact-uid"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Contact: 1770849610657274975
|
||||
--------------
|
||||
BEGIN:VCARD
|
||||
VERSION:3.0
|
||||
UID:1770849610657274975
|
||||
FN:John Doe
|
||||
EMAIL;TYPE=INTERNET:john@example.com
|
||||
TEL;TYPE=VOICE:555-1234
|
||||
END:VCARD
|
||||
```
|
||||
|
||||
### `nextcloud-create-contact` - Create a new contact
|
||||
|
||||
```bash
|
||||
# Create contact with fields
|
||||
nextcloud-create-contact \
|
||||
--name "John Doe" \
|
||||
--email "john@example.com" \
|
||||
--phone "555-1234"
|
||||
|
||||
# Create contact from vCard file
|
||||
nextcloud-create-contact --vcard /path/to/contact.vcf
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Create a contact
|
||||
nextcloud-create-contact --name "John Doe" --email "john@example.com" --phone "555-1234"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Contact created successfully
|
||||
```
|
||||
|
||||
### `nextcloud-delete-contact` - Delete a contact
|
||||
|
||||
```bash
|
||||
# Delete contact by UID
|
||||
nextcloud-delete-contact --uid "1770849610657274975"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
# Delete a contact
|
||||
nextcloud-delete-contact --uid "contact-uid"
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Contact deleted: 1770849610657274975
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Contact Management Workflow
|
||||
|
||||
```bash
|
||||
# Create a new contact
|
||||
nextcloud-create-contact --name "Jane Smith" --email "jane@example.com" --phone "555-5678"
|
||||
|
||||
# Verify contact was created
|
||||
nextcloud-list-contacts | grep "Jane"
|
||||
|
||||
# Retrieve contact details
|
||||
nextcloud-get-contact --uid "$(nextcloud-list-contacts | grep 'Jane' | awk '{print $2}')"
|
||||
```
|
||||
|
||||
### 2. Bulk Contact Import
|
||||
|
||||
```bash
|
||||
# Import contacts from vCard files
|
||||
for vcard in contacts/*.vcf; do
|
||||
nextcloud-create-contact --vcard "$vcard"
|
||||
done
|
||||
```
|
||||
|
||||
### 3. Contact Search Workflow
|
||||
|
||||
```bash
|
||||
# Search for contact by UID pattern
|
||||
nextcloud-list-contacts | grep "pattern"
|
||||
|
||||
# Get detailed contact info
|
||||
nextcloud-get-contact --uid "found-uid"
|
||||
```
|
||||
|
||||
### 4. Contact Cleanup
|
||||
|
||||
```bash
|
||||
# List all contacts
|
||||
nextcloud-list-contacts
|
||||
|
||||
# Delete specific contacts
|
||||
nextcloud-delete-contact --uid "old-contact-uid"
|
||||
|
||||
# Verify deletion
|
||||
nextcloud-list-contacts
|
||||
```
|
||||
|
||||
## vCard Format
|
||||
|
||||
The CLI tool generates vCard 3.0 format contacts:
|
||||
|
||||
```vcf
|
||||
BEGIN:VCARD
|
||||
VERSION:3.0
|
||||
UID:<timestamp>
|
||||
FN:<formatted-name>
|
||||
EMAIL;TYPE=INTERNET:<email>
|
||||
TEL;TYPE=VOICE:<phone>
|
||||
ORG:<company>
|
||||
TITLE:<title>
|
||||
END:VCARD
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The nextcloud-contacts binary provides clear error messages:
|
||||
|
||||
| Error | Meaning | Action |
|
||||
|-------|---------|--------|
|
||||
| Error: credentials not set at build time | Need to re-bootstrap | Ask skill to re-run bootstrap |
|
||||
| Error: UID is required for get-contact operation | Missing UID | Provide contact UID |
|
||||
| Error: contact name is required | Missing name | Provide --name flag |
|
||||
| unexpected status: 404 | Contact not found | Verify UID and address book |
|
||||
| unexpected status: 401 | Unauthorized | App token expired, re-bootstrap |
|
||||
| get contact failed with status: xxx | Read error | Check contact exists |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. No runtime configuration needed (credentials embedded)
|
||||
2. Store UIDs when creating contacts for later retrieval
|
||||
3. Verify operations by listing after create/delete
|
||||
4. Handle vCard format when importing from files
|
||||
5. Use display names not paths when referring to address books
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `~/bin/nextcloud-contacts` - Go binary for CardDAV operations
|
||||
- No external XML parsing needed (handled by Go)
|
||||
- vCard files use standard RFC 6350 format
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **nextcloud-files** - For storing contact photos as files
|
||||
- **nextcloud-calendar** - For linking contacts to calendar events
|
||||
|
||||
---
|
||||
|
||||
*OpenClaw skill wrapper for nextcloud-contacts Go binary with automatic app token retrieval*
|
||||
240
skills/nextcloud-files/SKILL.md
Normal file
240
skills/nextcloud-files/SKILL.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# Nextcloud Files Skill
|
||||
|
||||
**Purpose:** Manage files and folders on Nextcloud servers using the nextcloud-client CLI tool.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides file operations for Nextcloud using the nextcloud-client Go binary. The CLI tool handles all WebDAV operations and XML parsing.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Go compiler (for building CLI tool)
|
||||
- Nextcloud server URL
|
||||
- Nextcloud username
|
||||
- Nextcloud password (for app token retrieval)
|
||||
|
||||
## Bootstrap Process
|
||||
|
||||
**This skill will automatically build the CLI tool with your Nextcloud 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 the 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 the nextcloud-client binary was created
|
||||
5. **Immediately forget all credentials** (username, password, and app token are never stored)
|
||||
|
||||
**Step 3: You're ready!**
|
||||
- Use the tool without passing any credentials
|
||||
- The app token is embedded at compile time
|
||||
- Example: `nextcloud-list` (no --url, --user, --token needed)
|
||||
|
||||
**Security Note:**
|
||||
- **All credentials** (username, password, and app token) are only used during the bootstrap process
|
||||
- **App token is retrieved automatically** using your normal login credentials
|
||||
- **Credentials are never stored permanently** in any file or environment
|
||||
- **The app token is embedded** in the compiled binary, which stays on your local system only
|
||||
- **Do not distribute** the built binary outside your trusted environment
|
||||
|
||||
## Configuration
|
||||
|
||||
All credentials are embedded at compile time via Go ldflags. No runtime configuration needed.
|
||||
|
||||
### Build-Time Configuration (Recommended)
|
||||
|
||||
The skill will handle this automatically during bootstrap:
|
||||
```bash
|
||||
cd projects/nextcloud-integration/tools/go/nextcloud-client
|
||||
|
||||
go build -ldflags="-X 'main.BuildServerURL=https://teamworkapps.com' \
|
||||
-X 'main.BuildUsername=wltbagent@shortcutsolutions.net' \
|
||||
-X 'main.BuildToken=YOUR_APP_TOKEN'" \
|
||||
-o ~/bin/nextcloud-client .
|
||||
```
|
||||
|
||||
### 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 (Fallback)
|
||||
|
||||
Override credentials for specific commands 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` - List folder contents
|
||||
|
||||
```bash
|
||||
# List root folder
|
||||
nextcloud-list
|
||||
|
||||
# List specific folder
|
||||
nextcloud-list /Documents
|
||||
|
||||
# List recursively
|
||||
nextcloud-list /Documents --recursive
|
||||
```
|
||||
|
||||
### `nextcloud-upload` - Upload files
|
||||
|
||||
```bash
|
||||
# Upload file to root
|
||||
nextcloud-upload localfile.txt /remote/path.txt
|
||||
|
||||
# Upload multiple files
|
||||
nextcloud-upload *.pdf /Documents/
|
||||
|
||||
# Upload to specific folder
|
||||
nextcloud-upload report.pdf /Documents/Reports/
|
||||
```
|
||||
|
||||
### `nextcloud-download` - Download files
|
||||
|
||||
```bash
|
||||
# Download file
|
||||
nextcloud-download /remote/path.txt localfile.txt
|
||||
|
||||
# Download folder (requires manual implementation)
|
||||
```
|
||||
|
||||
### `nextcloud-mkdir` - Create folder
|
||||
|
||||
```bash
|
||||
# Create single folder
|
||||
nextcloud-mkdir /NewFolder
|
||||
|
||||
# Create nested folders (auto-parents)
|
||||
nextcloud-mkdir /Documents/2026/Projects
|
||||
```
|
||||
|
||||
### `nextcloud-delete` - Delete files/folders
|
||||
|
||||
```bash
|
||||
# Delete file
|
||||
nextcloud-delete /file.txt
|
||||
|
||||
# Delete folder (recursive)
|
||||
nextcloud-delete /OldFolder
|
||||
```
|
||||
|
||||
### `nextcloud-move` - Move/rename files
|
||||
|
||||
```bash
|
||||
# Move file
|
||||
nextcloud-move /old/path.txt /new/path.txt
|
||||
|
||||
# Rename file
|
||||
nextcloud-move /oldname.txt /newname.txt
|
||||
|
||||
# Move folder
|
||||
nextcloud-move /OldFolder /NewFolder
|
||||
```
|
||||
|
||||
### `nextcloud-copy` - Copy files
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
nextcloud-copy /source.txt /destination.txt
|
||||
|
||||
# Copy folder
|
||||
nextcloud-copy /SourceFolder /DestinationFolder
|
||||
```
|
||||
|
||||
### `nextcloud-info` - Get file metadata
|
||||
|
||||
```bash
|
||||
# Get file info
|
||||
nextcloud-info /Documents/report.pdf
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. File Management Workflow
|
||||
|
||||
```bash
|
||||
# Backup local files to Nextcloud
|
||||
nextcloud-upload local-file.txt /Backups/file.txt
|
||||
|
||||
# Organize with folders
|
||||
nextcloud-mkdir /Documents/2026
|
||||
nextcloud-move /Downloads/report.pdf /Documents/2026/report.pdf
|
||||
```
|
||||
|
||||
### 2. Folder Organization
|
||||
|
||||
```bash
|
||||
# Create project structure
|
||||
nextcloud-mkdir /Projects/WebsiteRedesign
|
||||
nextcloud-mkdir /Projects/WebsiteRedesign/Assets
|
||||
nextcloud-mkdir /Projects/WebsiteRedesign/Code
|
||||
|
||||
# Move files into folders
|
||||
nextcloud-move /homepage.html /Projects/WebsiteRedesign/
|
||||
nextcloud-move /style.css /Projects/WebsiteRedesign/Assets/
|
||||
```
|
||||
|
||||
### 3. Backup & Restore
|
||||
|
||||
```bash
|
||||
# Download folder for backup
|
||||
nextcloud-download /Documents documents-backup.zip
|
||||
|
||||
# Restore from backup
|
||||
# (Implementation needed for folder download as ZIP)
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
The nextcloud-client binary provides clear error messages:
|
||||
|
||||
| Error | Meaning | Action |
|
||||
|-------|---------|--------|
|
||||
| Error: URL, user, and token are required | Missing credentials | Re-run bootstrap process |
|
||||
| unexpected status: 401 | Unauthorized | App token expired, re-bootstrap |
|
||||
| unexpected status: 403 | Forbidden | Check app token permissions |
|
||||
| unexpected status: 404 | Not Found | File doesn't exist |
|
||||
| unexpected status: 409 | Conflict | Resource already exists |
|
||||
| unexpected status: 207 (expected 207 Multi-Status) | PROPFIND error | Check path and permissions |
|
||||
| upload failed with status: xxx | Upload error | Check file size and permissions |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. No runtime configuration needed (credentials embedded)
|
||||
2. Always include trailing slash in directory paths
|
||||
3. Check file sizes before large uploads
|
||||
4. Handle ETags - Check for concurrent updates (not yet implemented)
|
||||
5. Set Content-Type correctly - Binary handles this automatically
|
||||
6. Handle errors gracefully - CLI provides clear error messages
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `~/bin/nextcloud-client` - Go binary for WebDAV operations
|
||||
- `curl` - Used by Go binary internally
|
||||
- No XML parsing libraries needed (handled by Go)
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **nextcloud-contacts** - For storing contact photos as files
|
||||
- **nextcloud-calendar** - For attaching calendar events to files
|
||||
|
||||
---
|
||||
|
||||
*OpenClaw skill wrapper for nextcloud-client Go binary with automatic app token retrieval*
|
||||
450
skills/nextcloud-mail/SKILL.md
Normal file
450
skills/nextcloud-mail/SKILL.md
Normal file
@@ -0,0 +1,450 @@
|
||||
# Nextcloud Mail Skill
|
||||
|
||||
**Purpose:** Full-featured email client for Nextcloud with IMAP and SMTP support. Includes server-side search, attachment handling, and folder management.
|
||||
|
||||
**Location:** `~/bin/nextcloud-mail`
|
||||
|
||||
**Server:** https://teamworkapps.com (Nextcloud 25.0.13)
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap Process (Automatic)
|
||||
|
||||
The skill will guide you through setting up email credentials:
|
||||
|
||||
**What you need to provide:**
|
||||
- Nextcloud username
|
||||
- Nextcloud password (or app token)
|
||||
- IMAP server (default: teamworkapps.com)
|
||||
- SMTP server (default: teamworkapps.com)
|
||||
- IMAP port (default: 993 for SSL, 143 for STARTTLS)
|
||||
- SMTP port (default: 465 for SSL, 587 for STARTTLS)
|
||||
- Use SSL (default: true)
|
||||
- Ignore certificate validity (default: false)
|
||||
|
||||
**The skill will:**
|
||||
1. Ask for your email credentials
|
||||
2. Build the nextcloud-mail tool with compile-time credentials
|
||||
3. Immediately forget all credentials (never stored)
|
||||
4. Provide instructions for using the tool
|
||||
|
||||
**Why this approach:**
|
||||
- Credentials embedded at compile time (secure, local-only)
|
||||
- No environment variables needed at runtime
|
||||
- Simple command invocation
|
||||
|
||||
---
|
||||
|
||||
## Available Operations
|
||||
|
||||
### 1. List Folders
|
||||
List all IMAP folders/mailboxes.
|
||||
|
||||
```bash
|
||||
nextcloud-mail --op list-folders
|
||||
```
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
IMAP Folders:
|
||||
INBOX
|
||||
Sent
|
||||
Drafts
|
||||
Trash
|
||||
Archive
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. List Messages
|
||||
List messages in a folder with pagination.
|
||||
|
||||
```bash
|
||||
nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 25
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--folder`: IMAP folder name (default: INBOX)
|
||||
- `--page`: Page number (1-indexed, default: 1)
|
||||
- `--page-size`: Messages per page (default: 25)
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
Messages in INBOX (Page 1 of 3, showing 1-25 of 72):
|
||||
|
||||
UID: 1234
|
||||
From: John Doe <john@example.com>
|
||||
To: me@example.com
|
||||
Subject: Project Update
|
||||
Date: Fri, 20 Feb 2026 17:00:00 +0000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Get Message
|
||||
Retrieve message content and handle attachments.
|
||||
|
||||
```bash
|
||||
# Get message body
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234
|
||||
|
||||
# List attachments
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments
|
||||
|
||||
# Save attachments to a directory
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ./attachments
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--folder`: IMAP folder
|
||||
- `--uids`: Message UIDs (comma-separated)
|
||||
- `--list-attachments`: List attachments only
|
||||
- `--save-attachments`: Save attachments to disk
|
||||
- `--save-dir`: Directory for saving attachments (default: .)
|
||||
|
||||
**Example output (list attachments):**
|
||||
```
|
||||
UID: 1234
|
||||
From: John Doe <john@example.com>
|
||||
Subject: Project Update
|
||||
Attachments (2):
|
||||
1. report.pdf (application/pdf) - Part: 1.2
|
||||
2. image.png (image/png) - Part: 1.3
|
||||
```
|
||||
|
||||
**Example output (save attachments):**
|
||||
```
|
||||
UID: 1234
|
||||
From: John Doe <john@example.com>
|
||||
Subject: Project Update
|
||||
Saving attachments to ./attachments:
|
||||
Saved: report.pdf (1024576 bytes)
|
||||
Saved: image.png (45678 bytes)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Send Email
|
||||
Send email with attachments.
|
||||
|
||||
```bash
|
||||
# Simple email
|
||||
nextcloud-mail --op send-email \
|
||||
--from me@example.com \
|
||||
--to recipient@example.com \
|
||||
--subject "Test Email" \
|
||||
--body "This is a test email"
|
||||
|
||||
# Email with attachments
|
||||
nextcloud-mail --op send-email \
|
||||
--from me@example.com \
|
||||
--to recipient@example.com,recipient2@example.com \
|
||||
--subject "Report" \
|
||||
--body "Please find attached the report" \
|
||||
--attachments "./report.pdf,./image.png"
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--from`: Sender email address (required)
|
||||
- `--to`: Recipient email addresses (comma-separated, required)
|
||||
- `--subject`: Email subject
|
||||
- `--body`: Email body text
|
||||
- `--attachments`: Attachment file paths (comma-separated)
|
||||
|
||||
---
|
||||
|
||||
### 5. Delete Messages
|
||||
Delete messages by UID.
|
||||
|
||||
```bash
|
||||
# Delete single message
|
||||
nextcloud-mail --op delete-messages --folder INBOX --uids 1234
|
||||
|
||||
# Delete multiple messages
|
||||
nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235,1236
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--folder`: IMAP folder
|
||||
- `--uids`: Message UIDs (comma-separated, required)
|
||||
|
||||
**Note:** Messages are permanently deleted (no undo).
|
||||
|
||||
---
|
||||
|
||||
### 6. Move Messages
|
||||
Move messages between folders.
|
||||
|
||||
```bash
|
||||
# Move single message
|
||||
nextcloud-mail --op move-messages --folder INBOX --uids 1234 --dest-folder Archive
|
||||
|
||||
# Move multiple messages
|
||||
nextcloud-mail --op move-messages --folder INBOX --uids 1234,1235 --dest-folder Archive
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--folder`: Source folder
|
||||
- `--uids`: Message UIDs (comma-separated, required)
|
||||
- `--dest-folder`: Destination folder (required)
|
||||
|
||||
---
|
||||
|
||||
### 7. Search
|
||||
Perform server-side search.
|
||||
|
||||
```bash
|
||||
nextcloud-mail --op search --folder INBOX --query "project update"
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `--folder`: IMAP folder to search
|
||||
- `--query`: Search query (searches message text)
|
||||
|
||||
**Example output:**
|
||||
```
|
||||
Found 3 messages matching 'project update' in INBOX:
|
||||
|
||||
UID: 1234
|
||||
From: John Doe <john@example.com>
|
||||
Subject: Project Update
|
||||
Date: Fri, 20 Feb 2026 17:00:00 +0000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security and Configuration
|
||||
|
||||
### Credential Priority
|
||||
|
||||
The tool supports multiple configuration methods (in priority order):
|
||||
|
||||
1. **Build-time ldflags** (highest priority)
|
||||
- Embedded at compile time
|
||||
- Most secure
|
||||
- No runtime configuration needed
|
||||
|
||||
2. **Environment variables** (fallback)
|
||||
```bash
|
||||
export NEXTCLOUD_MAIL_IMAP_SERVER="teamworkapps.com"
|
||||
export NEXTCLOUD_MAIL_IMAP_PORT="993"
|
||||
export NEXTCLOUD_MAIL_IMAP_USER="username"
|
||||
export NEXTCLOUD_MAIL_IMAP_PASSWORD="password"
|
||||
export NEXTCLOUD_MAIL_SMTP_SERVER="teamworkapps.com"
|
||||
export NEXTCLOUD_MAIL_SMTP_PORT="465"
|
||||
export NEXTCLOUD_MAIL_SMTP_USER="username"
|
||||
export NEXTCLOUD_MAIL_SMTP_PASSWORD="password"
|
||||
```
|
||||
|
||||
3. **Command-line flags** (lowest priority)
|
||||
```bash
|
||||
nextcloud-mail --imap-server teamworkapps.com --imap-user username ...
|
||||
```
|
||||
|
||||
### SSL/TLS and Certificate Validation
|
||||
|
||||
By default, the tool uses SSL/TLS with certificate validation:
|
||||
|
||||
```bash
|
||||
# Use SSL/TLS with certificate validation (default)
|
||||
nextcloud-mail --ssl=true --ignore-certs=false
|
||||
|
||||
# Use SSL/TLS but ignore certificate warnings (for self-signed certs)
|
||||
nextcloud-mail --ssl=true --ignore-certs=true
|
||||
|
||||
# Use STARTTLS (non-SSL port)
|
||||
nextcloud-mail --ssl=false
|
||||
```
|
||||
|
||||
**Security Note:** Setting `--ignore-certs=true` is useful for self-signed certificates but reduces security. Use with caution.
|
||||
|
||||
---
|
||||
|
||||
## Use Cases and Workflows
|
||||
|
||||
### Workflow 1: Check for Important Emails
|
||||
|
||||
```bash
|
||||
# List recent messages in INBOX
|
||||
nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 10
|
||||
|
||||
# Get full message
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234
|
||||
```
|
||||
|
||||
### Workflow 2: Download Attachments
|
||||
|
||||
```bash
|
||||
# List attachments first
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments
|
||||
|
||||
# Create directory and save attachments
|
||||
mkdir -p ~/downloads/attachments
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ~/downloads/attachments
|
||||
```
|
||||
|
||||
### Workflow 3: Send Report with Attachments
|
||||
|
||||
```bash
|
||||
# Compile report and send
|
||||
nextcloud-mail --op send-email \
|
||||
--from me@example.com \
|
||||
--to client@example.com \
|
||||
--subject "Monthly Report - $(date +%Y-%m)" \
|
||||
--body "Please find the monthly report attached." \
|
||||
--attachments "./report.pdf,./summary.xlsx"
|
||||
```
|
||||
|
||||
### Workflow 4: Clean Up Inbox
|
||||
|
||||
```bash
|
||||
# Search for old emails
|
||||
nextcloud-mail --op search --folder INBOX --query "old newsletter"
|
||||
|
||||
# Move to archive
|
||||
nextcloud-mail --op move-messages --folder INBOX --uids 1234,1235,1236 --dest-folder Archive
|
||||
|
||||
# Delete spam
|
||||
nextcloud-mail --op delete-messages --folder INBOX --uids 7890,7891
|
||||
```
|
||||
|
||||
### Workflow 5: Monitor Specific Folder
|
||||
|
||||
```bash
|
||||
# Check drafts folder
|
||||
nextcloud-mail --op list-messages --folder Drafts --page 1
|
||||
|
||||
# Check sent items
|
||||
nextcloud-mail --op list-messages --folder Sent --page 1 --page-size 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Common Errors
|
||||
|
||||
**"failed to connect to IMAP server"**
|
||||
- Check server address and port
|
||||
- Verify SSL settings (`--ssl` flag)
|
||||
- Try `--ignore-certs=true` for self-signed certificates
|
||||
|
||||
**"IMAP login failed"**
|
||||
- Verify username and password
|
||||
- Check if account is locked
|
||||
- Ensure IMAP is enabled for the account
|
||||
|
||||
**"failed to select folder"**
|
||||
- Verify folder name (case-sensitive)
|
||||
- List folders first: `--op list-folders`
|
||||
- Check if folder exists
|
||||
|
||||
**"folder is read-only"**
|
||||
- Some folders (like shared folders) may not allow modifications
|
||||
- Check folder permissions
|
||||
|
||||
**"failed to send email"**
|
||||
- Verify SMTP server settings
|
||||
- Check sender address
|
||||
- Ensure SMTP authentication credentials are correct
|
||||
- Verify recipient email addresses
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Pagination** - Always use pagination for large folders
|
||||
```bash
|
||||
nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 25
|
||||
```
|
||||
|
||||
2. **Search Before Delete** - Verify messages before deletion
|
||||
```bash
|
||||
nextcloud-mail --op search --folder INBOX --query "newsletter"
|
||||
nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235
|
||||
```
|
||||
|
||||
3. **Attachment Management** - List attachments before saving
|
||||
```bash
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments
|
||||
nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ./attachments
|
||||
```
|
||||
|
||||
4. **Move Instead of Delete** - Use archive folder for safekeeping
|
||||
```bash
|
||||
nextcloud-mail --op move-messages --folder INBOX --uids 1234 --dest-folder Archive
|
||||
```
|
||||
|
||||
5. **Use Descriptive Subjects** - Makes searching easier
|
||||
```bash
|
||||
nextcloud-mail --op send-email \
|
||||
--from me@example.com \
|
||||
--to recipient@example.com \
|
||||
--subject "[PROJECT] Meeting Notes - 2026-02-20" \
|
||||
--body "Meeting notes attached."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Multiple Recipients
|
||||
|
||||
```bash
|
||||
nextcloud-mail --op send-email \
|
||||
--from me@example.com \
|
||||
--to "alice@example.com,bob@example.com,charlie@example.com" \
|
||||
--subject "Team Update" \
|
||||
--body "Team update for the week."
|
||||
```
|
||||
|
||||
### Custom IMAP/SMTP Servers
|
||||
|
||||
```bash
|
||||
# Override build-time credentials
|
||||
nextcloud-mail \
|
||||
--imap-server mail.example.com \
|
||||
--imap-port 993 \
|
||||
--smtp-server smtp.example.com \
|
||||
--smtp-port 465 \
|
||||
--op list-folders
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
```bash
|
||||
# Delete multiple emails found by search
|
||||
# First search to get UIDs
|
||||
nextcloud-mail --op search --folder INBOX --query "spam"
|
||||
|
||||
# Then delete the UIDs you want
|
||||
nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235,1236
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
Test your email setup:
|
||||
|
||||
```bash
|
||||
# 1. List folders (basic connectivity)
|
||||
nextcloud-mail --op list-folders
|
||||
|
||||
# 2. List messages (IMAP working)
|
||||
nextcloud-mail --op list-messages --folder INBOX --page 1
|
||||
|
||||
# 3. Send test email (SMTP working)
|
||||
nextcloud-mail --op send-email \
|
||||
--from me@example.com \
|
||||
--to me@example.com \
|
||||
--subject "Email Test" \
|
||||
--body "This is a test email from nextcloud-mail"
|
||||
|
||||
# 4. Search (server-side search working)
|
||||
nextcloud-mail --op search --folder INBOX --query "test"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Nextcloud Mail Skill - Full email integration with IMAP and SMTP*
|
||||
Reference in New Issue
Block a user