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:

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:

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

nextcloud-list-books

Example:

# 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

# List contacts in default book
nextcloud-list-contacts

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

Example:

# List contacts
nextcloud-list-contacts

Output:

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

nextcloud-get-contact - Retrieve a specific contact

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

Example:

# 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

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

# 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

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

Example:

# Delete a contact
nextcloud-delete-contact --uid "contact-uid"

Output:

Contact deleted: 1770849610657274975

Use Cases

1. Contact Management Workflow

# 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

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

3. Contact Search Workflow

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

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

4. Contact Cleanup

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

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