nextcloud

name	nextcloud
description	Full-featured Nextcloud integration for Hermes — manage files, notes, tasks, calendar events, and contacts via WebDAV, Nextcloud Notes API, and CalDAV/CardDAV. Works with self-hosted Nextcloud instances.
version	1.1.0
author	Hermes Agent
license	MIT
metadata	{"hermes":{"tags":["Nextcloud","WebDAV","Notes","Calendar","Tasks","Contacts","CalDAV","CardDAV","Files","Self-hosted"],"homepage":"https://github.com/NousResearch/hermes-agent","related_skills":["google-workspace"]}}

Nextcloud

Full-featured integration with self-hosted Nextcloud. Manage files, notes, tasks, calendar events, and contacts using WebDAV, the Nextcloud Notes REST API, and CalDAV/CardDAV protocols.

Requires: Nextcloud Notes app installed on the instance (for Notes features). All other features work with a standard Nextcloud installation.

Setup

Run the guided setup to configure credentials:

python3 ~/.hermes/skills/productivity/nextcloud/scripts/setup.py

The setup script will:

1. Ask for your Nextcloud URL, username, and App Password
2. Validate connectivity against your instance
3. Save credentials to ~/.hermes/nextcloud.env

Alternatively, set environment variables manually:

export NEXTCLOUD_URL="https://your-nextcloud.example.com"
export NEXTCLOUD_USER="your_username"
export NEXTCLOUD_TOKEN="***"
export NEXTCLOUD_TIMEZONE="Europe/Prague"  # optional, defaults to UTC

Creating an App Password

1. Log in to your Nextcloud instance
2. Go to Settings → Security → App passwords
3. Click Add new app password
4. Enter a name (e.g. hermes-agent) and click Create
5. Copy the generated password — it is shown only once

Verifying the Setup

NC="python3 ~/.hermes/skills/productivity/nextcloud/scripts/nextcloud_api.py"
$NC check

Expected output: {"status": "success", "data": {"authenticated": true, "user": "your_username"}}

Architecture

Feature	Protocol	Endpoint
Files	WebDAV	/remote.php/dav/files/<user>/
Notes	REST API	/index.php/apps/notes/api/v1/notes
Tasks	CalDAV (VTODO)	/remote.php/dav/calendars/<user>/
Calendar Events	CalDAV (VEVENT)	/remote.php/dav/calendars/<user>/
Contacts	CardDAV	/remote.php/dav/addressbooks/<user>/

Authentication: HTTP Basic Auth with App Password (user:token).

Usage

Define the convenience alias:

NC="python3 ~/.hermes/skills/productivity/nextcloud/scripts/nextcloud_api.py"

---

Files (WebDAV)

List directory contents

$NC files list --path "/Documents"
$NC files list  # root folder

Returns: {"status": "success", "data": [{"path": "...", "type": "file|dir", "size": N, "mtime": "ISO8601"}]}

Get file content

$NC files get --path "/Documents/notes.md"

Upload file

$NC files upload --path "/Documents/new-file.txt" --content "File content here"

Create directory

$NC files mkdir --path "/Documents/projects"

Delete file or directory

$NC files delete --path "/Documents/old-file.txt"

Warning: Deletion is permanent and recursive for directories.

Move / rename

$NC files move --src "/Documents/old-name.txt" --dst "/Documents/new-name.txt"

Search files

$NC files search --query "budget"

---

Notes (Nextcloud Notes API)

Requires the Notes app installed in Nextcloud.

List notes

$NC notes list
$NC notes list --category "work"

Get note by ID

$NC notes get --id 42

Create note

$NC notes create --title "Meeting Notes" --content "Discussion points..."
$NC notes create --title "Work Note" --content "..." --category "work"

Update note

$NC notes edit --id 42 --title "Updated Title" --content "New content"
$NC notes edit --id 42 --category "personal"

Delete note

$NC notes delete --id 42

---

Tasks (CalDAV VTODO)

List task lists (calendars)

$NC calendars list --type tasks

List tasks from a calendar

$NC tasks list
$NC tasks list --calendar "Personal"

Create task

$NC tasks create --title "Finish quarterly report" --due "2026-06-30T17:00:00Z" --priority 5
$NC tasks create --title "Call with client" --calendar "Work" --due "2026-06-15T10:00:00Z" --priority 3

Priority: 0 = none, 1 = highest, 9 = lowest.

Update task

$NC tasks edit --uid "abc123def" --title "New title" --priority 9
$NC tasks edit --uid "abc123def" --due "2026-07-01T12:00:00Z"

Mark task complete

$NC tasks complete --uid "abc123def"

Delete task

$NC tasks delete --uid "abc123def"

---

Calendar Events (CalDAV VEVENT)

List event calendars

$NC calendars list --type events

List events

$NC calendar list
$NC calendar list --from "2026-07-01T00:00:00Z" --to "2026-07-07T23:59:59Z"
$NC calendar list --calendar "Work"

Default range: next 7 days.

Create event

$NC calendar create --summary "Team Standup" --start "2026-07-01T09:00:00Z" --end "2026-07-01T09:30:00Z"
$NC calendar create --summary "Conference" --start "2026-09-15T08:00:00Z" --end "2026-09-17T18:00:00Z" --location "Prague" --calendar "Work"

Update event

$NC calendar edit --uid "xyz789" --summary "New Title"
$NC calendar edit --uid "xyz789" --start "2026-07-02T10:00:00Z" --end "2026-07-02T11:00:00Z"

Delete event

$NC calendar delete --uid "xyz789"

---

Contacts (CardDAV)

List address books

$NC addressbooks list

List contacts

$NC contacts list
$NC contacts list --addressbook "Personal"

Search contacts

$NC contacts search --query "John"

Get contact by UID

$NC contacts get --uid "contact-uid-string"

Create contact

$NC contacts create --name "John Doe" --email "[e-mail]" --phone "[phone]"
$NC contacts create --name "Jane Smith" --email "[e-mail]" --organization "Acme Corp" --title "Engineer"

Update contact

$NC contacts edit --uid "contact-uid-string" --phone "[phone]" --email "[e-mail]"

Delete contact

$NC contacts delete --uid "contact-uid-string"

---

Output Format

All commands return JSON:

{"status": "success", "data": {...}}
{"status": "error", "message": "Descriptive error message"}

For list operations, data is always an array even if empty: [].

---

Environment Variables

Variable	Required	Description
NEXTCLOUD_URL	Yes	Base URL of your Nextcloud instance (no trailing slash)
NEXTCLOUD_USER	Yes	Your Nextcloud username
NEXTCLOUD_TOKEN	Yes	App Password (from Settings → Security → App passwords)

Credentials are stored in ~/.hermes/nextcloud.env by the setup script. The skill reads them automatically if present.

---

Error Handling

HTTP Code	Meaning	Common Cause
401	Unauthorized	Invalid or expired App Password
403	Forbidden	User lacks permission for this resource
404	Not Found	Wrong path, or Notes app not installed
409	Conflict	Destination already exists (on move/rename)
424	Method Not Allowed	Feature not supported by server (e.g. Notes API)

---

Rules for Hermes Agent

1. Confirm before destructive operations — always show what will be deleted before running a delete command
2. Use App Password, never primary password — App Password can be revoked without affecting primary credentials
3. Respect rate limits — avoid rapid sequential API calls; batch reads where possible
4. Verify Notes app availability — if Notes API returns 404, inform the user the Notes app may not be installed
5. Handle missing credentials gracefully — if env vars are not set, prompt user to run setup.py