caldavpuller/README.md

CalDAV Calendar Synchronizer

A Rust-based command-line tool that synchronizes calendar events between Zoho Calendar and Nextcloud via CalDAV protocol. It allows you to selectively import events from specific Zoho calendars into a single Nextcloud calendar.

Features

• Selective Calendar Import: Choose which Zoho calendars to sync from
• Single Target Calendar: All events consolidated into one Nextcloud calendar
• Timezone Support: Handles events across different timezones correctly
• Next Week Focus: Optimized for importing events for the next 7 days
• Simple Data Transfer: Extracts only title, time, and duration as requested
• Secure Authentication: Uses app-specific passwords for security
• Dry Run Mode: Preview what would be synced before making changes

Quick Start

Prerequisites

• Rust 1.70+ (for building from source)
• Zoho account with CalDAV access
• Nextcloud instance with CalDAV enabled
• App-specific passwords for both services (recommended)

Installation

# Clone the repository
git clone ssh://git@gitea.soliverez.com.ar/alvaro/caldavpuller.git
cd caldavpuller

# Build the project
cargo build --release

# The binary will be at target/release/caldav-sync

Configuration

Copy the example configuration file:

cp config/example.toml config/config.toml

Edit config/config.toml with your settings:

# Zoho CalDAV Configuration (Source)
[zoho]
server_url = "https://caldav.zoho.com/caldav"
username = "your-zoho-email@domain.com"
password = "your-zoho-app-password"

# Select which calendars to import
selected_calendars = ["Work Calendar", "Personal Calendar"]

# Nextcloud Configuration (Target)
[nextcloud]
server_url = "https://your-nextcloud-domain.com"
username = "your-nextcloud-username"
password = "your-nextcloud-app-password"
target_calendar = "Imported-Zoho-Events"
create_if_missing = true

First Run

Test the configuration with a dry run:

./target/release/caldav-sync --debug --list-events

Perform a one-time sync:

./target/release/caldav-sync --once

Usage

Command Line Options

caldav-sync [OPTIONS]

Options:
  -c, --config <CONFIG>          Configuration file path [default: config/default.toml]
  -s, --server-url <SERVER_URL>  CalDAV server URL (overrides config file)
  -u, --username <USERNAME>      Username for authentication (overrides config file)
  -p, --password <PASSWORD>      Password for authentication (overrides config file)
      --calendar <CALENDAR>      Calendar name to sync (overrides config file)
  -d, --debug                    Enable debug logging
      --once                     Perform a one-time sync and exit
      --full-resync              Force a full resynchronization
      --list-events              List events and exit
  -h, --help                     Print help
  -V, --version                  Print version

Common Operations

1. List Available Events:

   caldav-sync --list-events
   

2. One-Time Sync:

   caldav-sync --once
   

3. Full Resynchronization:

   caldav-sync --full-resync
   

4. Override Configuration:

   caldav-sync --username "user@example.com" --password "app-password" --once
   

Configuration

Environment Variables

You can also use environment variables:

export CALDAV_SERVER_URL="https://caldav.zoho.com/caldav"
export CALDAV_USERNAME="your-email@domain.com"
export CALDAV_PASSWORD="your-app-password"
export CALDAV_CALENDAR="Work Calendar"

./target/release/caldav-sync

Complete Configuration Example

See config/example.toml for a comprehensive configuration example with all available options.

Security Considerations

1. Use App Passwords: Never use your main account password
2. Secure Configuration: Set appropriate file permissions on config files
3. SSL/TLS: Always use HTTPS connections
4. Log Management: Be careful with debug logs that may contain sensitive data

Troubleshooting

Common Issues

1. Authentication Failures:

   • Verify app-specific passwords are correctly set up
   • Check that CalDAV is enabled in both services
   • Ensure correct server URLs

2. Calendar Not Found:

   • Use --list-events to see available calendars
   • Check calendar name spelling
   • Verify permissions

3. Timezone Issues:

   • Events are automatically converted to UTC internally
   • Original timezone information is preserved
   • Check system timezone if times seem off

4. SSL Certificate Issues:

   • Ensure server URLs use HTTPS
   • Check if custom certificates need to be configured

Debug Mode

Enable debug logging for troubleshooting:

caldav-sync --debug --list-events

This will show detailed HTTP requests, responses, and processing steps.

More Information

• Development & Design: See DEVELOPMENT.md
• Contributing: See CONTRIBUTING.md
• License: See LICENSE

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the debug output with --debug
3. Open an issue on the project repository
4. Include your configuration (with sensitive data removed) and debug logs