nextcloud-integration/README.md

# 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:

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

**Example:**
```bash
./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

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

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

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

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

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

```bash
./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)

**⚠️ Password Limitation:**
The build script uses simple shell variable substitution for credentials. Passwords containing spaces, double quotes (`"`), or dollar signs (`$`) may cause the build to fail. If your password contains these characters, consider using a simpler password or manually editing the build command.

---

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