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:
```bash
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:

```bash
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

```bash
# List root folder
nextcloud-list

# List specific folder
nextcloud-list /Documents

# List recursively
nextcloud-list /Documents --recursive
```

### `nextcloud-upload` - Upload files

```bash
# 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

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

# Download folder (requires manual implementation)
```

### `nextcloud-mkdir` - Create folder

```bash
# Create single folder
nextcloud-mkdir /NewFolder

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

### `nextcloud-delete` - Delete files/folders

```bash
# Delete file
nextcloud-delete /file.txt

# Delete folder (recursive)
nextcloud-delete /OldFolder
```

### `nextcloud-move` - Move/rename files

```bash
# 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

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

# Copy folder
nextcloud-copy /SourceFolder /DestinationFolder
```

### `nextcloud-info` - Get file metadata

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

## Use Cases

### 1. File Management Workflow

```bash
# 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

```bash
# 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

```bash
# 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*