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:

bashCopy code
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:

bashCopy code
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

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

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

Architecture

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

Usage

Define the convenience alias:

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

Files (WebDAV)

List directory contents

bashCopy code
$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

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

Upload file

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

Create directory

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

Delete file or directory

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

Warning: Deletion is permanent and recursive for directories.

Move / rename

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

Search files

bashCopy code
$NC files search --query "budget"

Notes (Nextcloud Notes API)

Requires the Notes app installed in Nextcloud.

List notes

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

Get note by ID

bashCopy code
$NC notes get --id 42

Create note

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

Update note

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

Delete note

bashCopy code
$NC notes delete --id 42

Tasks (CalDAV VTODO)

List task lists (calendars)

bashCopy code
$NC calendars list --type tasks

List tasks from a calendar

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

Create task

bashCopy code
$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

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

Mark task complete

bashCopy code
$NC tasks complete --uid "abc123def"

Delete task

bashCopy code
$NC tasks delete --uid "abc123def"

Calendar Events (CalDAV VEVENT)

List event calendars

bashCopy code
$NC calendars list --type events

List events

bashCopy code
$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

bashCopy code
$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

bashCopy code
$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

bashCopy code
$NC calendar delete --uid "xyz789"

Contacts (CardDAV)

List address books

bashCopy code
$NC addressbooks list

List contacts

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

Search contacts

bashCopy code
$NC contacts search --query "John"

Get contact by UID

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

Create contact

bashCopy code
$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

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

Delete contact

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

Output Format

All commands return JSON:

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

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

Environment Variables

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

Error Handling

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