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

# Nextcloud Contacts Skill

**Purpose:** Manage contacts and address books on Nextcloud servers using the nextcloud-contacts CLI tool.

## Overview

This skill provides contact operations for Nextcloud using the nextcloud-contacts Go binary. The CLI tool handles all CardDAV operations and vCard parsing.

## Prerequisites

- Go compiler (for building CLI tool)
- Nextcloud server URL
- Nextcloud username
- Nextcloud password (for app token retrieval)
- Contacts app enabled on Nextcloud

## Bootstrap Process

**This skill will automatically build all three Nextcloud CLI tools with your 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)

**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 all three binaries were created
5. **Immediately forget** all credentials (username, password, and app token are never stored)

**Step 3: You're ready!**
- Use any tool without passing credentials (app token is embedded at compile time)
- Example: `nextcloud-list-books` (no --url, --user, --token needed)
- Example: `nextcloud-create-contact --name "John" --email "john@example.com"`

**Security Note:**
- **All credentials** (username, password, and app token) are only used during the bootstrap process
- **App token is retrieved automatically** - you don't need to find it manually
- **Credentials are never stored permanently** in any file or environment
- **The app token is embedded** in the compiled binary at build time
- **The compiled binary stays** on your local system only
- **Do not distribute** built binaries outside your trusted environment

## Configuration

All credentials are embedded at compile time via Go ldflags. No runtime configuration needed.

### Build-Time Configuration (Automatic)

The skill will handle this automatically during bootstrap:
```bash
cd projects/nextcloud-integration/tools/go/nextcloud-contacts

go build -ldflags="-X 'main.BuildServerURL=https://teamworkapps.com' \
                 -X 'main.BuildUsername=wltbagent@shortcutsolutions.net' \
                 -X 'main.BuildToken=YOUR_APP_TOKEN'" \
  -o ~/bin/nextcloud-contacts .
```

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

### `nextcloud-list-books` - List all address books

```bash
nextcloud-list-books
```

**Example:**
```bash
# List all address books
nextcloud-list-books
```

**Output:**
```
Address Books:
--------------
Name: Contacts
Path: contacts
ETag: 

Name: Recently contacted
Path: z-app-generated--contactsinteraction--recent
ETag: 
```

### `nextcloud-list-contacts` - List contacts in an address book

```bash
# List contacts in default book
nextcloud-list-contacts

# List contacts in specific book
nextcloud-list-contacts --book "work-contacts"
```

**Example:**
```bash
# List contacts
nextcloud-list-contacts
```

**Output:**
```
Contacts in 'contacts':
--------------
UID: 1770849610657274975
ETag: "037658b635c2523a8cf70085e81e4f69"
```

### `nextcloud-get-contact` - Retrieve a specific contact

```bash
# Get contact by UID
nextcloud-get-contact --uid "1770849610657274975"
```

**Example:**
```bash
# Get contact
nextcloud-get-contact --uid "contact-uid"
```

**Output:**
```
Contact: 1770849610657274975
--------------
BEGIN:VCARD
VERSION:3.0
UID:1770849610657274975
FN:John Doe
EMAIL;TYPE=INTERNET:john@example.com
TEL;TYPE=VOICE:555-1234
END:VCARD
```

### `nextcloud-create-contact` - Create a new contact

```bash
# Create contact with fields
nextcloud-create-contact \
  --name "John Doe" \
  --email "john@example.com" \
  --phone "555-1234"

# Create contact from vCard file
nextcloud-create-contact --vcard /path/to/contact.vcf
```

**Example:**
```bash
# Create a contact
nextcloud-create-contact --name "John Doe" --email "john@example.com" --phone "555-1234"
```

**Output:**
```
Contact created successfully
```

### `nextcloud-delete-contact` - Delete a contact

```bash
# Delete contact by UID
nextcloud-delete-contact --uid "1770849610657274975"
```

**Example:**
```bash
# Delete a contact
nextcloud-delete-contact --uid "contact-uid"
```

**Output:**
```
Contact deleted: 1770849610657274975
```

## Use Cases

### 1. Contact Management Workflow

```bash
# Create a new contact
nextcloud-create-contact --name "Jane Smith" --email "jane@example.com" --phone "555-5678"

# Verify contact was created
nextcloud-list-contacts | grep "Jane"

# Retrieve contact details
nextcloud-get-contact --uid "$(nextcloud-list-contacts | grep 'Jane' | awk '{print $2}')"
```

### 2. Bulk Contact Import

```bash
# Import contacts from vCard files
for vcard in contacts/*.vcf; do
  nextcloud-create-contact --vcard "$vcard"
done
```

### 3. Contact Search Workflow

```bash
# Search for contact by UID pattern
nextcloud-list-contacts | grep "pattern"

# Get detailed contact info
nextcloud-get-contact --uid "found-uid"
```

### 4. Contact Cleanup

```bash
# List all contacts
nextcloud-list-contacts

# Delete specific contacts
nextcloud-delete-contact --uid "old-contact-uid"

# Verify deletion
nextcloud-list-contacts
```

## vCard Format

The CLI tool generates vCard 3.0 format contacts:

```vcf
BEGIN:VCARD
VERSION:3.0
UID:<timestamp>
FN:<formatted-name>
EMAIL;TYPE=INTERNET:<email>
TEL;TYPE=VOICE:<phone>
ORG:<company>
TITLE:<title>
END:VCARD
```

## Error Handling

The nextcloud-contacts binary provides clear error messages:

| Error | Meaning | Action |
|-------|---------|--------|
| Error: credentials not set at build time | Need to re-bootstrap | Ask skill to re-run bootstrap |
| Error: UID is required for get-contact operation | Missing UID | Provide contact UID |
| Error: contact name is required | Missing name | Provide --name flag |
| unexpected status: 404 | Contact not found | Verify UID and address book |
| unexpected status: 401 | Unauthorized | App token expired, re-bootstrap |
| get contact failed with status: xxx | Read error | Check contact exists |

## Best Practices

1. No runtime configuration needed (credentials embedded)
2. Store UIDs when creating contacts for later retrieval
3. Verify operations by listing after create/delete
4. Handle vCard format when importing from files
5. Use display names not paths when referring to address books

## Dependencies

- `~/bin/nextcloud-contacts` - Go binary for CardDAV operations
- No external XML parsing needed (handled by Go)
- vCard files use standard RFC 6350 format

## Related Skills

- **nextcloud-files** - For storing contact photos as files
- **nextcloud-calendar** - For linking contacts to calendar events

---

*OpenClaw skill wrapper for nextcloud-contacts Go binary with automatic app token retrieval*