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-01popcalendar://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 option | What it does |
|---|---|
/open | Open a session, or update and bring forward an existing session. |
/toggle | Close the session if it exists, otherwise open it. |
/update | Update content or geometry without opening an absent session or taking focus. |
/move | Change only geometry without opening an absent session or taking focus. |
/close | Close the session. Closing an absent session has no effect. |
Content and geometry
| Command or option | What it does |
|---|---|
presentation | window by default, popup, or fullscreen. Close a live session before changing its presentation. |
mode | month, two-months, year, two-years, month-year, or month-two-years. The default is year. |
date | Gregorian YYYY-MM-DD in the app's time zone. Defaults to the range's first date, or today. |
start, end | Inclusive YYYY-MM-DD endpoints. Supply both, with start no later than end. |
selection | Use clear to remove the selection. Cannot be combined with start and end. |
calendar-set | A saved calendar-set UUID or current to copy the active filter. Obtain IDs with the CLI or Shortcuts. Unknown IDs are rejected. |
display | For 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, height | Content 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. |
anchor | A popup anchor rectangle as x,y,width,height in global screen coordinates. Cannot be combined with x and y. |
x, y | Explicit position instead of an anchor. Supply both. A popup with an explicit position has no arrow. |
coordinates | appkit 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. |
arrow | auto, top, bottom, left, right, or none. Names the popup edge containing the arrow. Placement may flip to keep the panel visible. |
callback | A 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 contentsFocus 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 contentsReceive 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%3DexampleExisting 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 option | What it does |
|---|---|
pc-session | The original session name. |
pc-start, pc-end | First and last selected civil days, inclusive. |
pc-ranges | A JSON array of [start, end] pairs preserving separate ranges, up to 128. |
pc-time-zone | The time zone identifier for the returned dates. |