nextcloud-integration/skills/nextcloud-files/SKILL.md

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:

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:

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

# List root folder
nextcloud-list

# List specific folder
nextcloud-list /Documents

# List recursively
nextcloud-list /Documents --recursive

nextcloud-upload - Upload files

# 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

# Download file
nextcloud-download /remote/path.txt localfile.txt

# Download folder (requires manual implementation)

nextcloud-mkdir - Create folder

# Create single folder
nextcloud-mkdir /NewFolder

# Create nested folders (auto-parents)
nextcloud-mkdir /Documents/2026/Projects

nextcloud-delete - Delete files/folders

# Delete file
nextcloud-delete /file.txt

# Delete folder (recursive)
nextcloud-delete /OldFolder

nextcloud-move - Move/rename files

# 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

# Copy file
nextcloud-copy /source.txt /destination.txt

# Copy folder
nextcloud-copy /SourceFolder /DestinationFolder

nextcloud-info - Get file metadata

# Get file info
nextcloud-info /Documents/report.pdf

Use Cases

1. File Management Workflow

# 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

# 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

# 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