Automation documentation
Command-line reference
Integrate popCalendar with your Dock replacement or other Mac tools. Open calendars, choose dates, manage plans and export images through the CLI.
These guides cover popCalendar 1.3 and later. Some actions require a newer system version, as noted below.
A full calendar experience for your tool
Add popCalendar to your Dock replacement, launcher, menu bar utility or any other Mac tool. Offer a rich calendar experience without implementing one yourself, using native calendar windows, anchored popups and date selection through the CLI.
Developers can contact us for a free popCalendar promo code and hands-on support while building an integration.
Every tool that implements popCalendar integration will receive a dedicated section on popcalendar.app as an officially supported integration. Let us know when yours is ready.
Back to contentsRun from the app bundle
With popCalendar installed, no separate CLI package is needed. Run the main executable using its full path. Every command starts with --. Running without a command launches the normal app.
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --helpOptionally append the executable directory to PATH for the current terminal session. You can add the same line to your shell configuration yourself. Use the app's actual location if it was moved or renamed. The Setapp executable is also named popCalendar. Use a full path to choose an edition when both are installed.
export PATH="${PATH:+$PATH:}"'/Applications/popCalendar.app/Contents/MacOS'
popCalendar --help Back to contents Display a calendar in Terminal
Use --terminal to print the calendar without opening a calendar window. Enable Terminal calendars in Settings > Automation & Privacy first. Preview opens an example sheet with commands you can copy. Basic calendars run locally. Requested private data is read through the app in the background.
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --interactive
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --year 2027Without an explicit layout, a full year is shown if it fits, otherwise a month. Interactive mode adapts on resize until you choose a layout or select a range. Pipes, JSON and agenda-only output default to one month.
Back to contentsEvents, plans and working days
Use --events to include events, --agenda for an event list, --plans to mark saved plans, and --working-days for your work schedule. A calendar-set filter applies only to that command and does not change the active set. --search matches titles and locations. Grant calendar access in the app before requesting events.
popCalendar --terminal --events today --agenda
popCalendar --terminal --events week --calendar-set current
popCalendar --terminal --months 3 --plans all --working-days
popCalendar --terminal --events month --search meeting --limit 20
popCalendar --terminal --start 2027-03-01 --end 2027-03-14 --events rangeThe week option means the next seven days from --date, or today. A range includes both endpoints. Without an explicit selection, events for range cover the displayed months. Dates and headings use the Gregorian calendar.
Back to contentsNavigate in interactive mode
Use arrows or h/j/k/l to move through days, n/p for periods, m/y for month/year and t for today. Press v to mark the start and end of a range, c to clear it, g to go to a date, / to search, and ? for help. Press q or Escape to quit.
Toggle events with e, agenda with a, plans with b, working days with d and week numbers with w. Press s for the next calendar set, r to refresh, and PageUp/PageDown or Space to scroll.
Full-word commands also work and are case-insensitive. In immediate-key mode, press the colon key first, type a command and press Enter. If the footer asks for Enter, type the command directly and press Enter. Escape cancels an active prompt before quitting.
month year next previous today
left right up down range clear
events agenda plans working-days sets week-numbers
goto 2027-03-01
search meeting
refresh page-up page-down home end
help quit exit Back to contents Terminal output options
Choose a date, month, year, mode or 1 to 24 months. Supply --start and --end together, without another date or mode option. Use --time-zone, --first-weekday and --week-numbers to control the calendar. --width accepts 32 to 240 columns, --limit accepts 1 to 500 events, and --color accepts auto, always or never.
popCalendar --terminal --mode two-years --date 2027-01-01 --week-numbers
popCalendar --terminal --month 2027-03 --time-zone Europe/Kyiv --first-weekday monday
popCalendar --terminal --year 2027 --width 120 --color never > calendar.txt
popCalendar --terminal --events today --json > agenda.jsonRedirected output is plain text. --json returns structured data without ANSI formatting and cannot be combined with --interactive or --color always. Terminal commands are read-only and do not change events, plans or calendar sets.
Back to contentsOpen and control calendars
Options accept --option value or --option=value. The default session is cli. Reusing a session updates the same window. Use different names for independent windows. All six modes are supported.
popCalendar --open --session work --mode two-years --date 2027-01-01
popCalendar --popup --session picker --mode month --anchor 400,850,40,24 --size 520x720
popCalendar --update --session picker --date 2027-03-01
popCalendar --move --session picker --anchor 600,850,40,24
popCalendar --close --session pickerFor a full-screen overlay, use --presentation fullscreen with --display current, main, or a display UUID. It fills one display without creating a macOS Space. Escape or toggling the same session dismisses it. Full-screen sessions reject size, position, anchor, arrow, and coordinate options. Close the session before changing its presentation.
popCalendar --toggle --session overview --presentation fullscreen --mode two-years --display current Back to contents Return a confirmed date selection
--select opens a picker and waits for confirmation. Its default timeout is 300 seconds. Set --timeout to a value from 1 through 86400. Escape, closing the picker, or Control-C cancels it. Up to 128 separate ranges are returned from the last-used calendar pane. Without --json, each line contains START END. Both dates are included.
popCalendar --select --session picker --mode month --date 2027-03-01 --json --timeout 300{"version":1,"status":"selected","session":"picker","timeZone":"America/Los_Angeles","ranges":[{"start":"2027-03-01","end":"2027-03-07"}]} Back to contents Plans, working days, and images
Replace SET_UUID and PLAN_UUID with IDs returned by --sets and --plans. Use different UUIDs for REQUEST_UUID and NEW_REQUEST_UUID. The permission requirements are described in the automation overview.
| Command or option | What it does |
|---|---|
--help | Print the complete command and option reference. |
--version | Print the app version and build. |
--capabilities [--json] | Return supported commands and limits without opening the app. |
--doctor [--json] [--timeout SECONDS] | Check app identity, permission switches, and communication with the app. |
--sets [--json] | Return saved calendar-set names and IDs. |
--sessions [--json] | Return open integration session IDs on Mac. |
--plans [--name SEARCH] [--id UUID] [--json] | Return saved plans, their ranges, and repetition information. Filter by name or ID. |
--create-plan --name NAME --start YYYY-MM-DD --end YYYY-MM-DD [--request-id UUID] | Save a named inclusive date range and return the plan ID. |
--duplicate-plan --id UUID --name NAME [--request-id UUID] | Duplicate a saved plan under a new name and return its ID. |
--open-plan --id UUID | Open a saved plan using its current ranges and repetition settings. |
--activate-set --calendar-set UUID | Change the active calendar set while keeping the current date and layout. |
--working-days --start YYYY-MM-DD --end YYYY-MM-DD | Count working days using the enabled schedule and all-day time-off calendars. Both endpoints count. |
--shift-working-days --start YYYY-MM-DD --count INTEGER | Move forward or backward by working days. The starting day does not count. |
--pause-chimes --minutes INTEGER | Pause chimes for the specified number of minutes, up to seven days. |
--resume-chimes | End the pause while preserving the configured chime schedule and enabled state. |
--export --start YYYY-MM-DD --end YYYY-MM-DD [--calendar-set UUID] [--plans UUID,UUID] [--events] | Export a PNG for at most two calendar years. Include only requested saved plans. Event circles are omitted unless requested. |
API dates use Gregorian YYYY-MM-DD in the app's time zone. Working-day calculations require an enabled working schedule. Date queries are limited to ten years and shifts to 2,600 working days. Failed event reads produce an error instead of treating time off as zero.
Use the same request UUID and identical details when retrying plan creation or duplication. A retry returns the existing ID. Different details fail. Do not reuse that UUID after editing or deleting the result. A timeout or cancellation does not undo a change already applied.
popCalendar --sets --json
popCalendar --plans --name Holiday --json
popCalendar --create-plan --name Holiday --start 2027-08-02 --end 2027-08-13 --request-id REQUEST_UUID
popCalendar --duplicate-plan --id PLAN_UUID --name Variation --request-id NEW_REQUEST_UUID--export writes PNG bytes to standard output. Redirect them to a file. The requested range is highlighted and normal windows and saved settings stay unchanged. CLI export produces PNG, not PDF.
popCalendar --export --start 2027-01-01 --end 2027-12-31 --calendar-set SET_UUID --plans PLAN_UUID --events > calendar.png Back to contents Results and failures
Control commands wait up to 60 seconds for acceptance by default. --wait is optional. --no-wait confirms delivery only and cannot be combined with --timeout or used for selection, data, or diagnostics. Acceptance does not mean events have finished loading.
Data commands return JSON. With --json, success or failure is one JSON object on standard output. Errors include errorCode, message, and exitCode. Without --json, errors use standard error. --export returns image bytes and cannot use --json.
{"version":1,"status":"error","errorCode":"invalid_arguments","message":"Unknown option --example.","exitCode":64,"command":"open"}| Exit code | What it does |
|---|---|
0 | Success |
2 | Selection cancelled |
3 | Timed out |
4 | App launch or connection failed |
5 | Request rejected by the app |
64 | Invalid command or arguments |
70 | Internal or response-channel error |
128 + signal | Interrupted by a signal, including 130 for Control-C |
Diagnose a connection
--doctor may start the app in the background. Its default timeout is ten seconds. It does not change permissions or return calendar contents. Successful JSON diagnostics appear under result.diagnostics with connection set to connected and permissionSource set to app. Failed checks include a top-level diagnostics object using local permission values, which may differ from an unresponsive app's unsaved state.
popCalendar --doctor --json Back to contents 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. |
--clear-selection | 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 contents