Automation documentation

Apple Shortcuts

Build workflows with calendar sets, confirmed date ranges, saved plans, working days, and calendar images.

These guides cover popCalendar 1.3 and later. Some actions require a newer system version, as noted below.

Find popCalendar in Shortcuts

Open the updated app once, then add an action in Apple Shortcuts and search for popCalendar. Actions are available on macOS 13 and later and iOS 17 and later. Date-picking actions and suggested App Shortcuts on Mac require macOS 13.3 or later. macOS 12 users can use the CLI and URL interface.

The popCalendar section includes ready-to-use Open Calendar, Choose Calendar Date Ranges, Count Working Days, Pause Chimes, and Resume Chimes shortcuts. Pause Chimes defaults to 60 minutes. No imported shortcut file is required.

Back to contents

Actions on Mac, iPhone, and iPad

ActionWhat it does
Open CalendarChoose a calendar set, one of the six layouts, and an optional starting date.
Get Calendar SetsReturn saved calendar-set names and IDs.
Choose Calendar Date RangesSelect and confirm dates, returning typed ranges with start, end, inclusive day count, and time zone.
Get Saved PlansReturn saved plans, their ranges, and repetition information. Filter by name or ID.
Create Saved PlanSave a named inclusive date range and return the plan ID.
Duplicate Saved PlanDuplicate a saved plan under a new name and return its ID.
Open Saved PlanOpen a saved plan using its current ranges and repetition settings.
Switch Active Calendar SetChange the active calendar set while keeping the current date and layout.
Count Working DaysCount working days using the enabled schedule and all-day time-off calendars. Both endpoints count.
Add Working DaysMove forward or backward by working days. The starting day does not count.
Pause ChimesPause chimes for the specified number of minutes, up to seven days.
Resume ChimesEnd the pause while preserving the configured chime schedule and enabled state.
Export Calendar ImageExport a PNG for at most two calendar years. Include only requested saved plans. Event circles are omitted unless requested.
Back to contents

Calendar sets and platform behavior

Enable private-data access to list saved sets by name. Choices use stable IDs, so renaming a set does not break a shortcut. Deleting a set produces an error instead of opening a different set. Native actions do not need the Mac external-control permission.

On Mac, Open Calendar creates an independent window with a copied filter. Its default session is shortcuts. Reusing that session updates the same window. On iPhone and iPad, it opens the Calendar tab and applies the chosen mode, date, and active set. Other iPad windows keep their browsing dates and layouts.

Back to contents

Additional Mac controls

Control Calendar opens, toggles, updates, moves, or closes named sessions using the same options as the URL interface. Choose a window, popup, or full-screen overlay. Get Calendar Sessions lists their IDs. Get Calendar Command Information returns the version, reference, capabilities, or automation diagnostics.

Select Calendar Dates returns confirmed ranges as JSON or plain text. Choose Calendar Date Ranges returns typed values instead. The default picker timeout is 300 seconds. Escape or closing the picker cancels it. Native Stop cancellation is supported on macOS and iOS 26.4 and later. Older versions retain Cancel and the timeout.

Back to contents

Build a workflow

  • Choose Calendar Date Ranges, repeat with each range, then Count Working Days.
  • Get Calendar Sets, Choose from List, then Open Calendar with the chosen set.
  • Get Saved Plans, choose a plan, then Open Saved Plan or Duplicate Saved Plan. Supply a stable request UUID when retrying creation or duplication.
  • Export Calendar Image, then Save File, Share, or Save to Photo Album. The export returns a PNG file.
  • Switch Active Calendar Set and Pause Chimes when starting focused work. Resume Chimes afterward. Enable the relevant permissions on each device first.
Back to contents