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

> Master gogcli recurring calendar events. Learn to set recurrence rules with --rrule and add multiple custom alerts using the --reminder flag. Create events that work for you.

- Repository: [Peter Steinberger/gogcli](https://github.com/steipete/gogcli)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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.

```bash
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`](https://github.com/steipete/gogcli/blob/main/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.

```bash
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`](https://github.com/steipete/gogcli/blob/main/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.

```bash
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`](https://github.com/steipete/gogcli/blob/main/internal/cmd/calendar_build.go)** – Contains `buildRecurrence`, `parseReminder`, and `buildReminders` for assembling event components
- **[`internal/cmd/calendar_edit.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/calendar_edit.go)** – Houses `CalendarCreateCmd.Run` and `CalendarEditCmd.Run` for API interaction and payload construction
- **[`internal/cmd/calendar_recurrence.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/calendar_recurrence.go)** – Implements `recurrenceUntil` and `truncateRecurrence` for handling recurring series modifications
- **[`internal/cmd/calendar_print.go`](https://github.com/steipete/gogcli/blob/main/internal/cmd/calendar_print.go)** – Provides `printEventReminders` for formatting reminder output in human-readable mode
- **[`internal/googleapi/calendar.go`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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`](https://github.com/steipete/gogcli/blob/main/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.