Automation documentation

URL scheme reference

Open a calendar window, anchored popup, or full-screen overlay from another Mac app.

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

Open a calendar from another app

This interface is for macOS 12 and later. Enable External app and CLI control first. Use popcalendar for the standard edition and popcalendar-setapp for Setapp. Build URLs with URLComponents and URLQueryItem, percent-encoding nested callback URLs as a single value.

popcalendar://integration/open?v=1&session=com.example.calendar&presentation=window&mode=two-years&date=2027-01-01
popcalendar://integration/toggle?v=1&session=com.example.picker&presentation=popup&mode=month&anchor=400,850,40,24&width=520&height=720&arrow=top
Back to contents

Commands and sessions

Every URL requires v=1 and a session name of 1 through 128 ASCII letters, digits, dots, underscores, or hyphens. Up to eight sessions can be open, including one popup or full-screen overlay. Opening another transient view replaces the previous transient view. Regular windows remain open.

Command or optionWhat it does
/openOpen a session, or update and bring forward an existing session.
/toggleClose the session if it exists, otherwise open it.
/updateUpdate content or geometry without opening an absent session or taking focus.
/moveChange only geometry without opening an absent session or taking focus.
/closeClose the session. Closing an absent session has no effect.
Back to contents

Content and geometry

Command or optionWhat it does
presentationwindow by default, popup, or fullscreen. Close a live session before changing its presentation.
modemonth, two-months, year, two-years, month-year, or month-two-years. The default is year.
dateGregorian YYYY-MM-DD in the app's time zone. Defaults to the range's first date, or today.
start, endInclusive YYYY-MM-DD endpoints. Supply both, with start no later than end.
selectionUse clear to remove the selection. Cannot be combined with start and end.
calendar-setA saved calendar-set UUID or current to copy the active filter. Obtain IDs with the CLI or Shortcuts. Unknown IDs are rejected.
displayFor full-screen overlays only. current uses the pointer's display, main uses the primary display, or supply a display UUID. Disconnected displays fall back to an available screen.
width, heightContent dimensions in logical points, each from 240 through 8192. Supply both. Popups keep the requested size from the first visible frame. Regular resizable windows may grow to meet readable minimums. Screen bounds take precedence. CLI also accepts --size WIDTHxHEIGHT.
anchorA popup anchor rectangle as x,y,width,height in global screen coordinates. Cannot be combined with x and y.
x, yExplicit position instead of an anchor. Supply both. A popup with an explicit position has no arrow.
coordinatesappkit uses the lower-left of the primary screen. top-left measures down from its upper-left. Secondary displays can have negative coordinates. Values are points, not pixels.
arrowauto, top, bottom, left, right, or none. Names the popup edge containing the arrow. Placement may flip to keep the panel visible.
callbackA registered custom URL scheme for returning explicitly confirmed dates.

The CLI uses the same names with a -- prefix, except selection=clear becomes --clear-selection. Full-screen overlays reject all geometry options except display. Unknown or duplicate parameters, malformed dates, and URLs over 16 KiB are rejected as a whole.

Back to contents

Focus and window lifetime

Sessions own their dates, layout, selection, and filter. They do not replace ordinary calendar windows and are not restored after quitting. Update and move do not activate the app. Popups dismiss on outside clicks, focus loss, Escape, or Space changes. Child popovers close first. Full-screen overlays also dismiss when switching apps.

For native callers, use NSWorkspace.open with an explicit application URL and OpenConfiguration.activates set to false for popup, full-screen, update, move, and close requests. Send move when your window moves and close when it closes. A successful URL delivery is not a protocol acknowledgement. Use the CLI or Shortcuts when you need an acknowledged result.

Back to contents

Receive selected dates

The user must confirm before the callback runs. Cancel, focus loss, and quit return nothing. Only dates, their time zone, and the session identifier are sent. No events or calendar contents are included. HTTP, HTTPS, file, data, JavaScript, and popCalendar callbacks are rejected.

popcalendar://integration/open?v=1&session=choose-trip&mode=month&callback=my-app%3A%2F%2Fcalendar-selection%3Ftoken%3Dexample

Existing callback query parameters are preserved. Do not use the reserved result names below in your callback URL. Validate the expected session and your own opaque token when receiving a result. Never include credentials in a URL.

Command or optionWhat it does
pc-sessionThe original session name.
pc-start, pc-endFirst and last selected civil days, inclusive.
pc-rangesA JSON array of [start, end] pairs preserving separate ranges, up to 128.
pc-time-zoneThe time zone identifier for the returned dates.
Back to contents