Nextcloud Integration

Overview: Complete Nextcloud integration with CLI tools and OpenClaw skills for Files, Contacts, and Calendar apps.

Server: https://teamworkapps.com (Nextcloud 25.0.13)

---

✅ Automatic Token Retrieval Added

Bootstrap Process

All three skills now include an automatic bootstrap process:

Flow:

1. User provides normal Nextcloud credentials (username + password)
2. Skill authenticates to Nextcloud automatically
3. Skill retrieves/generates an app token
4. Skill builds all three CLI tools with app token
5. Skill immediately forgets all credentials
6. User can use tools without passing any credentials

Benefits:

• ✅ No need to manually find/create app tokens
• ✅ User experience is simpler (just username + password)
• ✅ All credentials are forgotten immediately (security)
• ✅ All tools built together with same token

Security:

• Username and password only used during authentication (temporary)
• App token is retrieved from Nextcloud settings
• All credentials are never stored permanently
• App token is embedded in compiled binary (local-only)

---

Quick Start

Bootstrap Process (Automatic)

All Nextcloud SKILL.md files now include a secure bootstrap process:

The skill will:

1. Ask for your normal Nextcloud credentials (username and password)
2. Authenticate to Nextcloud automatically
3. Retrieve or generate an app token
4. Build all three CLI tools with the app token
5. Immediately forget all credentials (never stored)
6. Provide instructions to use tools without passing credentials

Why this approach:

• You don't need to manually find/create app tokens
• App token is retrieved automatically from your normal login
• All credentials are forgotten immediately after build
• App token is embedded in compiled binary (secure, local-only)

Example flow:

User: "Hey, use the Nextcloud skill"
Skill: "I'll set up your Nextcloud tools. What's your Nextcloud username and password?"
User: "wltbagent@shortcutsolutions.net" and "mypassword"
Skill: [Authenticates to Nextcloud, retrieves token, builds tools, forgets credentials]
Skill: "All done! Now you can use: nextcloud-client, nextcloud-contacts, nextcloud-calendar"

Security:

• Username and password are only used during bootstrap (authentication)
• Never stored in any file or environment variable
• App token is embedded in compiled binary (local system only)
• Do not distribute built binaries

---

Manual Build (Advanced)

If you prefer manual control, you can build tools with explicit app token:

cd projects/nextcloud-integration
./build.sh <server-url> <username> <token>

Example:

./build.sh https://teamworkapps.com wltbagent@shortcutsolutions.net 1b8a28ca2fc26820fee3f9a8524c351b

This builds all three CLI tools with credentials embedded at compile time.

---

Components

1. CLI Tools (Go binaries)

Tool	Location	Purpose
nextcloud-client	~/bin/nextcloud-client	File operations (WebDAV)
nextcloud-contacts	~/bin/nextcloud-contacts	Contact management (CardDAV)
nextcloud-calendar	~/bin/nextcloud-calendar	Calendar management (CalDAV)
nextcloud-mail	~/bin/nextcloud-mail	Email client (IMAP/SMTP)

Features:

• Full CRUD operations for all three apps
• Compile-time credential configuration (via ldflags)
• Runtime fallback to environment variables
• Command-line flag override
• Clear error messages

Configuration Priority:

1. Build-time ldflags (highest priority)
2. Environment variables
3. Command-line flags (lowest priority)

2. OpenClaw Skills

Skill	Location	Wraps
nextcloud-files	skills/nextcloud-files/SKILL.md	nextcloud-client
nextcloud-contacts	skills/nextcloud-contacts/SKILL.md	nextcloud-contacts
nextcloud-calendar	skills/nextcloud-calendar/SKILL.md	nextcloud-calendar
nextcloud-mail	skills/nextcloud-mail/SKILL.md	nextcloud-mail

Each skill provides:

• Tool reference with examples
• Use cases and workflows
• Error handling guide
• Best practices

---

Usage Examples

Files

# List root directory
nextcloud-client --op list --path "/"

# Upload a file
nextcloud-client --op upload --local file.txt --path "/remote.txt"

# Download a file
nextcloud-client --op download --path "/remote.txt" --local file.txt

Contacts

# List address books
nextcloud-contacts --op list-books

# Create a contact
nextcloud-contacts --op create-contact --name "John Doe" --email "john@example.com"

# List contacts
nextcloud-contacts --op list-contacts

Calendar

# List calendars
nextcloud-calendar --op list-calendars

# Create an event
nextcloud-calendar --op create-event --summary "Meeting" \
  --start "2026-02-12T10:00:00Z" --end "2026-02-12T11:00:00Z"

# List events
nextcloud-calendar --op list-events

Email (IMAP/SMTP)

⚠️ Important: The Nextcloud Mail integration uses different credentials from other Nextcloud tools (Files, Contacts, Calendar).

• Other tools: Use Nextcloud API credentials (server URL + username + API token)
• Mail: Uses IMAP/SMTP credentials (IMAP hostname, SMTP hostname, username, password)

These are separate authentication systems with different credentials. See skills/nextcloud-mail/SKILL.md for details.

# List folders
nextcloud-mail --op list-folders

# List messages with pagination
nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 25

# Get message
nextcloud-mail --op get-message --folder INBOX --uids 1234

# List attachments
nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments

# Save attachments
nextcloud-mail --op get-message --folder INBOX --uids 1234 --save-attachments --save-dir ./attachments

# Send email
nextcloud-mail --op send-email \
  --from me@example.com \
  --to recipient@example.com \
  --subject "Test" \
  --body "This is a test"

# Send email with attachments
nextcloud-mail --op send-email \
  --from me@example.com \
  --to recipient@example.com \
  --subject "Report" \
  --body "Report attached" \
  --attachments "./report.pdf,./image.png"

# Delete messages
nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235

# Move messages
nextcloud-mail --op move-messages --folder INBOX --uids 1234 --dest-folder Archive

# Search messages
nextcloud-mail --op search --folder INBOX --query "project update"

---

Architecture Decisions

Why CLI Tools + Skills?

1. Token Efficiency - Binary handles logic, LLM just calls it
2. Accuracy - Compiled Go > shell scripts
3. Reusability - Tools work outside OpenClaw
4. Testability - Easy to verify independently

Why Compile-Time Credentials?

1. Security - Credentials embedded at build, not in environment
2. Simplicity - No runtime configuration needed
3. Reliability - Binary always has credentials ready

Security Note: Binaries contain credentials in clear text. Do not distribute built binaries.

---

Building

Manual Build

Build individual tools:

# Files
cd tools/go/nextcloud-client
go build -ldflags="-X 'main.BuildServerURL=...' -X 'main.BuildUsername=...' -X 'main.BuildToken=...'" -o ~/bin/nextcloud-client .

# Contacts
cd tools/go/nextcloud-contacts
go build -ldflags="-X 'main.BuildServerURL=...' -X 'main.BuildUsername=...' -X 'main.BuildToken=...'" -o ~/bin/nextcloud-contacts .

# Calendar
cd tools/go/nextcloud-calendar
go build -ldflags="-X 'main.BuildServerURL=...' -X 'main.BuildUsername=...' -X 'main.BuildToken=...'" -o ~/bin/nextcloud-calendar .

Automated Build

Use the provided build script:

./build.sh <server-url> <username> <token>

The build script will:

1. Build Nextcloud API tools (Files, Contacts, Calendar) with the provided credentials
2. Prompt you for separate IMAP/SMTP credentials for the email integration
3. Build nextcloud-mail with email-specific credentials
4. Install all binaries to ~/bin/

Email credentials needed:

• IMAP server hostname (default: teamworkapps.com)
• IMAP port (default: 993 for SSL)
• IMAP username and password
• SMTP server hostname (default: teamworkapps.com)
• SMTP port (default: 465 for SSL)
• SMTP username and password
• SSL/TLS setting (default: yes)

✅ Special Character Support: The build script uses multiple -ldflags arguments to handle all special characters safely, including:

• Spaces
• Double quotes (")
• Hash signs (#)
• Dollar signs ($)
• At signs (@)
• Exclamation marks (!)
• Percentage signs (%)
• Ampersands (&)
• And any other special characters

---

Testing

All tools have been tested and verified working:

Component	Test	Status
nextcloud-client list	List files	✅ Pass
nextcloud-client upload	Upload test file	✅ Pass
nextcloud-client download	Download and verify	✅ Pass
nextcloud-client info	Get file metadata	✅ Pass
nextcloud-client delete	Delete test items	✅ Pass
nextcloud-contacts list-books	List address books	✅ Pass
nextcloud-contacts create-contact	Create test contact	✅ Pass
nextcloud-contacts delete-contact	Delete test contact	✅ Pass
nextcloud-calendar list-calendars	List calendars	✅ Pass
nextcloud-calendar create-event	Create test event	✅ Pass
nextcloud-calendar delete-event	Delete test event	✅ Pass

---

Progress Tracking

See PROGRESS-2026-02-11.md for detailed development history.

---

Not Implemented

• Notes app - REST API unresponsive, requires investigation
• Deck app - Not installed on server
• Talk app - Not installed on server
• Bookmarks app - Not installed on server

---

Complete Nextcloud integration with Files, Contacts, and Calendar