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.

Contact support@apptrust.app

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 contents

Run 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" --help

Optionally 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 2027

Without 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 contents

Events, 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 range

The 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 contents

Navigate 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.json

Redirected 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 contents

Open 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 picker

For 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 optionWhat it does
--helpPrint the complete command and option reference.
--versionPrint 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 UUIDOpen a saved plan using its current ranges and repetition settings.
--activate-set --calendar-set UUIDChange the active calendar set while keeping the current date and layout.
--working-days --start YYYY-MM-DD --end YYYY-MM-DDCount working days using the enabled schedule and all-day time-off calendars. Both endpoints count.
--shift-working-days --start YYYY-MM-DD --count INTEGERMove forward or backward by working days. The starting day does not count.
--pause-chimes --minutes INTEGERPause 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 --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 codeWhat it does
0Success
2Selection cancelled
3Timed out
4App launch or connection failed
5Request rejected by the app
64Invalid command or arguments
70Internal or response-channel error
128 + signalInterrupted by a signal, including 130 for Control-C
Back to contents

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 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.
--clear-selectionRemove 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