txt2ical

Minimal tool to convert CSV files to iCalendar (.ics) format.

Installation

chmod +x txt2ical

Usage

# Basic usage
./txt2ical < input.csv > output.ics

# With options
./txt2ical --buffer 15 --location "Office" < input.csv > output.ics

# All options combined
./txt2ical -b 10 -l "Dentist Office" -d "Please arrive early" -p "[Medical] " < input.csv > output.ics

Options

• -b, --buffer N - Add N minutes buffer before and after each event. Original times are preserved in the description.
• -l, --location STRING - Set location field for all events
• -d, --description TEXT - Set description text for all events
• -p, --prefix STRING - Prefix all event subjects with the given string
• -r, --reminder N - Add reminder N minutes before (positive) or after (negative) event start
• -h, --help - Show help message

CSV Format

The CSV must have a header line and three columns:

Date,Subject,Time
23.12.2025,Meeting,14:30
24.12.2025,Appointment,10:00 - 11:30

• Date: DD.MM.YYYY format
• Subject: Event title (any text)
• Time: Either HH:MM (1 hour default duration) or HH:MM - HH:MM (explicit range)

Examples

Basic Conversion

./txt2ical < zahnarzt.csv > zahnarzt.ics

With Buffer Time

Add 15 minutes before and after each appointment:

./txt2ical --buffer 15 < zahnarzt.csv > zahnarzt.ics

The description field will show: "Original: 13:30 - 13:45, Buffer: 15 minutes"

With Reminders

Add a reminder 15 minutes before each appointment:

./txt2ical --reminder 15 < zahnarzt.csv > zahnarzt.ics

Experimental: Reminder after event starts:

./txt2ical --reminder -10 < zahnarzt.csv > zahnarzt.ics

This creates a reminder 10 minutes after the event starts. Note that most calendar applications don't expose "after-start" reminders in their UI, but the iCalendar standard supports it. Test with your calendar app to see if it works.

Complete Example

./txt2ical \
  --buffer 10 \
  --location "Zahnarztpraxis Dr. Med" \
  --description "Bitte 10 Minuten vorher da sein" \
  --prefix "[Zahnarzt] " \
  --reminder 20 \
  < zahnarzt.csv > zahnarzt.ics

This will:

• Add 10 minutes buffer to each event
• Set location for all events
• Add custom description (after buffer info)
• Prefix all subjects with "[Zahnarzt] "
• Add reminder 20 minutes before event starts

Import the resulting .ics file into any calendar application (Google Calendar, Apple Calendar, Outlook, etc.).

Technical Details

Text Field Escaping

The tool properly escapes special characters in all text fields (SUMMARY, LOCATION, DESCRIPTION) per RFC 5545:

• Commas (,) → \,
• Semicolons (;) → \;
• Backslashes (\) → \\

This ensures fields like locations with addresses (e.g., "Street 123, Berlin") import correctly without being truncated at the comma.

Reminders (VALARM)

Reminders are implemented using the iCalendar VALARM component with ACTION:DISPLAY:

• Positive values create reminders before event start: --reminder 15 → TRIGGER:-PT15M
• Negative values create reminders after event start: --reminder -10 → TRIGGER:PT10M

Note: While the RFC 5545 standard supports after-start reminders, most calendar applications only expose before-start reminders in their UI. The functionality is standards-compliant, but application support varies.