Nextcloud

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// | | Notes | REST API | /index.php/apps/notes/api/v1/notes | | Tasks | CalDAV (VTODO) | /remote.php/dav/calendars// | | Calendar Events | CalDAV (VEVENT) | /remote.php/dav/calendars// | | Contacts | CardDAV | /remote.php/dav/addressbooks// |

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 "john@example.com" --phone "+420123456789"
$NC contacts create --name "Jane Smith" --email "jane@example.com" --organization "Acme Corp" --title "Engineer"

Update contact

$NC contacts edit --uid "contact-uid-string" --phone "+420987654321" --email "newemail@example.com"

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adnw-vinc
• Source: adnw-vinc/hermes-nextcloud
• License: MIT

Install and usage instructions live in the source repository linked above.