Creating Recurring Calendar Events with Reminders in gogcli: A Complete Guide

Use the --rrule flag to define recurrence patterns and the --reminder flag (up to 5 times) to attach custom alerts when creating calendar events with gogcli.

Creating recurring calendar events with reminders in gogcli involves translating CLI arguments into the precise JSON structures required by the Google Calendar API. The tool, authored by Peter Steinberger, provides a thin but robust wrapper that handles RRULE formatting, reminder validation, and event payload assembly through specific helper functions in its command layer.

How gogcli Handles Recurring Events and Reminders

The CLI assembles three distinct components before sending data to Google's servers:

• Recurrence rules – Collected via --rrule flags and cleaned by buildRecurrence in internal/cmd/calendar_build.go
• Reminder configurations – Parsed from --reminder flags using parseReminder, validated, and limited to five entries per event
• Event payload – Constructed in CalendarCreateCmd.Run within internal/cmd/calendar_edit.go, combining the recurrence slice and reminders object

Creating Recurring Events with RRULE

Understanding the buildRecurrence Function

In internal/cmd/calendar_build.go (lines 104-118), the buildRecurrence function processes the string slice collected from --rrule flags. It filters out empty entries and returns a clean slice of RRULE strings ready for the calendar.Event struct.

RRULE Syntax and Validation

The CLI passes RRULE values unchanged to the Google Calendar API, supporting standard iCalendar recurrence formats. You can specify frequency, interval, count, until dates, and by-day rules.

gog calendar create primary \
  --summary "Team Sync" \
  --from 2025-01-06T10:00:00Z \
  --to 2025-01-06T11:00:00Z \
  --rrule "RRULE:FREQ=WEEKLY;BYDAY=MO" \
  --reminder "popup:30m" \
  --reminder "email:1d"

This command creates a weekly Monday meeting with two reminders: a popup 30 minutes before and an email one day prior.

Configuring Event Reminders

The parseReminder and buildReminders Functions

The reminder parsing logic resides in internal/cmd/calendar_build.go. The parseReminder function (lines 57-71) splits the input string by colon, validates the method (popup or email), and calls parseDuration to convert human-readable strings like 30m, 2h, 1d, or 1w into minutes.

The buildReminders function (lines 81-120) collects all parsed reminders, enforces the five-reminder limit, and constructs the calendar.EventReminders object.

Reminder Limits and API Payload Structure

Google Calendar allows a maximum of five custom reminders per event. In buildReminders, if more than five non-empty reminders are supplied, the function returns an error before reaching the API.

The resulting payload sets UseDefault: false and populates the Overrides slice with calendar.EventReminder structs. The ForceSendFields entry ensures the API recognizes the custom reminder list rather than applying default settings.

gog calendar create primary \
  --summary "Project Deadline" \
  --from 2025-03-15T09:00:00Z \
  --to 2025-03-15T10:00:00Z \
  --rrule "RRULE:FREQ=DAILY;COUNT=5" \
  --reminder "email:1w" \
  --reminder "popup:1d" \
  --reminder "popup:1h"

Editing Instances of Recurring Series

Truncating Recurrence with truncateRecurrence

When editing a single instance of a recurring event, gogcli must prevent changes from affecting future occurrences. The truncateRecurrence function in internal/cmd/calendar_recurrence.go (lines 87-130) handles this by rewriting the RRULE to end just before the edited instance.

The recurrenceUntil Calculation Logic

The recurrenceUntil function (lines 33-55) calculates the boundary for the truncated series. It converts the original start time into a half-open range [min, max) and subtracts one second from the original start time (or one day for date-only events) to generate the UNTIL= value.

gog calendar edit primary abc123def456 \
  --instance-start 2025-01-20T10:00:00Z \
  --summary "Rescheduled Sync" \
  --reminder "popup:10m"

This command truncates the original series to end before January 20th, creating a new instance with updated details while preserving the historical recurrence pattern.

Key Source Files and Implementation Details

Understanding the codebase helps when debugging complex recurrence scenarios or contributing to the project:

• internal/cmd/calendar_build.go – Contains buildRecurrence, parseReminder, and buildReminders for assembling event components
• internal/cmd/calendar_edit.go – Houses CalendarCreateCmd.Run and CalendarEditCmd.Run for API interaction and payload construction
• internal/cmd/calendar_recurrence.go – Implements recurrenceUntil and truncateRecurrence for handling recurring series modifications
• internal/cmd/calendar_print.go – Provides printEventReminders for formatting reminder output in human-readable mode
• internal/googleapi/calendar.go – Thin wrapper around the Google Calendar service used by all calendar commands

Summary

• gogcli wraps the Google Calendar API to create recurring events using standard iCalendar RRULE strings passed via the --rrule flag
• The buildRecurrence function in internal/cmd/calendar_build.go cleans and validates recurrence rules before API submission
• Reminders use the syntax method:duration (e.g., popup:30m, email:1d) and are limited to five per event by the buildReminders function
• Editing a single instance of a recurring series triggers truncateRecurrence in internal/cmd/calendar_recurrence.go to end the original series before the modified instance
• All event creation logic flows through CalendarCreateCmd.Run in internal/cmd/calendar_edit.go

Frequently Asked Questions

What is the maximum number of reminders I can attach to a gogcli event?

You can attach up to five custom reminders per event. The buildReminders function in internal/cmd/calendar_build.go explicitly checks the length of the reminder slice and returns an error if you exceed this limit, which matches the Google Calendar API constraints.

How do I clear custom reminders and revert to calendar defaults?

Pass an empty reminder string using --reminder "". When buildReminders receives an empty input, it returns nil, which causes the application to set UseDefault: true in the API payload and add the field to ForceSendFields, effectively removing custom overrides and restoring the calendar's default notification settings.

What RRULE formats does gogcli support?

gogcli supports any valid iCalendar RRULE string passed via the --rrule flag, such as RRULE:FREQ=WEEKLY;BYDAY=MO for weekly Monday events or RRULE:FREQ=DAILY;COUNT=5 for five consecutive days. The buildRecurrence function passes these values unchanged to the Google Calendar API after filtering empty entries.

How does gogcli prevent editing a recurring event from affecting future occurrences?

When you edit a specific instance using the --instance-start flag, gogcli invokes truncateRecurrence in internal/cmd/calendar_recurrence.go. This function calculates a new UNTIL= value set to one second before the instance being edited (or one day before for date-only events), effectively terminating the original series and isolating your changes to the specific instance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}