Документація автоматизації

Довідка командного рядка

Інтегруйте popCalendar у власну заміну Dock або інші інструменти для Mac. Відкривайте календарі, вибирайте дати, керуйте планами та експортуйте зображення через CLI.

Ці посібники описують popCalendar 1.3 та новіші версії. Деякі дії потребують новішої версії системи, як зазначено нижче.

Повноцінний календар для вашого інструмента

Додайте popCalendar до власної заміни Dock, засобу запуску програм, утиліти для смуги меню чи будь-якого іншого інструмента для Mac. Запропонуйте багаті можливості календаря без потреби створювати його самостійно, використовуючи нативні вікна календаря, прив'язані спливні вікна та вибір дат через CLI.

Розробники можуть звернутися до нас по безкоштовний промокод popCalendar і практичну допомогу під час створення інтеграції.

Напишіть на support@apptrust.app

Кожен інструмент, у якому реалізовано інтеграцію popCalendar, отримає окремий розділ на popcalendar.app як офіційно підтримувана інтеграція. Повідомте нам, коли ваша інтеграція буде готова.

До змісту

Запуск із пакета програми

Якщо popCalendar уже встановлено, окремий пакет CLI не потрібен. Запускайте основний виконуваний файл за повним шляхом. Усі команди починаються з --. Запуск без команди відкриває звичайну програму.

"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --help

За бажанням додайте каталог виконуваного файла до PATH для поточного сеансу термінала. Той самий рядок можна вручну додати до налаштувань оболонки. Якщо програму переміщено або перейменовано, використовуйте її фактичне розташування. Виконуваний файл Setapp також має назву popCalendar. Якщо встановлено обидві версії, вибирайте потрібну повним шляхом.

export PATH="${PATH:+$PATH:}"'/Applications/popCalendar.app/Contents/MacOS'
popCalendar --help
До змісту

Показати календар у Терміналі

Використовуйте --terminal, щоб вивести календар без відкриття його вікна. Спочатку ввімкніть календарі в Терміналі в Налаштуваннях > Автоматизація та приватність. Перегляд відкриває панель прикладу з командами, які можна скопіювати. Звичайні календарі працюють локально. Запитані приватні дані читаються через програму у фоновому режимі.

"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --interactive
"/Applications/popCalendar.app/Contents/MacOS/popCalendar" --terminal --year 2027

Якщо макет не задано, показується повний рік, коли він уміщується, або місяць. Інтерактивний режим пристосовується до зміни розміру, доки ви не виберете макет або діапазон. Для конвеєрів, JSON і виводу лише списку подій типовим є один місяць.

До змісту

Події, плани та робочі дні

Додайте --events для подій, --agenda для списку подій, --plans для позначення збережених планів і --working-days для робочого графіка. Фільтр набору календарів діє лише для цієї команди й не змінює активний набір. --search шукає в назвах і місцях. Перед запитом подій надайте програмі доступ до календарів.

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

Параметр week означає наступні сім днів від --date або від сьогодні. Діапазон включає обидві крайні дати. Без явного вибору події для range охоплюють показані місяці. Дати й заголовки використовують григоріанський календар.

До змісту

Навігація в інтерактивному режимі

Використовуйте стрілки або h/j/k/l для переходу між днями, n/p для періодів, m/y для місяця чи року та t для сьогодні. Натисніть v, щоб позначити початок і кінець діапазону, c для очищення, g для переходу до дати, / для пошуку та ? для довідки. Для виходу натисніть q або Escape.

Перемикайте події клавішею e, список подій клавішею a, плани клавішею b, робочі дні клавішею d та номери тижнів клавішею w. Натисніть s для наступного набору календарів, r для оновлення, PageUp/PageDown або Space для прокручування.

Команди повними словами також працюють і не залежать від регістру. У режимі миттєвих клавіш спочатку натисніть клавішу двокрапки, введіть команду й натисніть Enter. Якщо нижній рядок просить Enter, одразу введіть команду й натисніть Enter. Escape спершу скасовує активний запит введення, а потім виходить.

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
До змісту

Параметри виводу в Терміналі

Виберіть дату, місяць, рік, режим або від 1 до 24 місяців. Задавайте --start і --end разом, без іншого параметра дати чи режиму. Налаштовуйте календар через --time-zone, --first-weekday і --week-numbers. --width приймає від 32 до 240 стовпців, --limit від 1 до 500 подій, а --color значення auto, always або 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

Переспрямований вивід є звичайним текстом. --json повертає структуровані дані без форматування ANSI й не поєднується з --interactive або --color always. Команди Термінала лише читають дані й не змінюють події, плани чи набори календарів.

До змісту

Відкриття та керування календарями

Параметри приймають --option value або --option=value. Типова назва сеансу cli. Повторне використання сеансу оновлює те саме вікно. Для незалежних вікон використовуйте різні назви. Підтримуються всі шість режимів.

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

Для повноекранного календаря використовуйте --presentation fullscreen із --display current, main або UUID дисплея. Він займає один дисплей без створення простору macOS. Escape або повторне перемикання того самого сеансу закриває його. Повноекранні сеанси відхиляють розмір, позицію, прив'язку, стрілку та координати. Перед зміною способу показу закрийте сеанс.

popCalendar --toggle --session overview --presentation fullscreen --mode two-years --display current
До змісту

Отримання підтвердженого вибору дат

--select відкриває вибір дат і чекає підтвердження. Типовий час очікування становить 300 секунд. --timeout можна встановити від 1 до 86400. Escape, закриття вікна вибору або Control-C скасовує дію. Повертається до 128 окремих діапазонів з останньої використаної панелі календаря. Без --json кожен рядок містить START END. Обидві дати включено.

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"}]}
До змісту

Плани, робочі дні та зображення

Замініть SET_UUID і PLAN_UUID ідентифікаторами, які повертають --sets і --plans. Використовуйте різні UUID для REQUEST_UUID і NEW_REQUEST_UUID. Вимоги до дозволів описано в огляді автоматизації.

Команда або параметрДія
--helpВиводить повну довідку команд і параметрів.
--versionВиводить версію та номер збірки програми.
--capabilities [--json]Повертає підтримувані команди й обмеження без відкриття програми.
--doctor [--json] [--timeout SECONDS]Перевіряє ідентифікацію програми, дозволи та зв'язок із нею.
--sets [--json]Повертає назви й ідентифікатори збережених наборів календарів.
--sessions [--json]Повертає ідентифікатори відкритих сеансів інтеграції на Mac.
--plans [--name SEARCH] [--id UUID] [--json]Повертає збережені плани, їхні діапазони та інформацію про повторення. Можна фільтрувати за назвою або ідентифікатором.
--create-plan --name NAME --start YYYY-MM-DD --end YYYY-MM-DD [--request-id UUID]Зберігає іменований діапазон дат включно з обома межами та повертає ідентифікатор плану.
--duplicate-plan --id UUID --name NAME [--request-id UUID]Дублює збережений план під новою назвою та повертає його ідентифікатор.
--open-plan --id UUIDВідкриває збережений план із поточними діапазонами та налаштуваннями повторення.
--activate-set --calendar-set UUIDЗмінює активний набір календарів зі збереженням поточної дати й режиму показу.
--working-days --start YYYY-MM-DD --end YYYY-MM-DDРахує робочі дні за ввімкненим графіком і календарями відсутності з подіями на весь день. Обидві межі враховуються.
--shift-working-days --start YYYY-MM-DD --count INTEGERПереміщує дату вперед або назад на робочі дні. Початковий день не враховується.
--pause-chimes --minutes INTEGERПризупиняє сигнали на вказану кількість хвилин, щонайбільше на сім днів.
--resume-chimesЗавершує паузу зі збереженням налаштованого розкладу й стану ввімкнення сигналів.
--export --start YYYY-MM-DD --end YYYY-MM-DD [--calendar-set UUID] [--plans UUID,UUID] [--events]Експортує PNG щонайбільше за два календарні роки. Включає лише запитані плани. Кружечки подій додаються лише за запитом.

Дати API використовують григоріанський формат YYYY-MM-DD у часовому поясі програми. Обчислення робочих днів потребують увімкненого робочого графіка. Запити дат обмежено десятьма роками, а зсуви 2600 робочими днями. Помилка читання подій повертає помилку, а не нуль днів відсутності.

Повторюючи створення або дублювання плану, використовуйте той самий UUID запиту й ідентичні дані. Повтор поверне вже наявний ідентифікатор. Інші дані спричинять помилку. Не використовуйте UUID повторно після редагування чи видалення результату. Завершення часу очікування або скасування не відкочує вже застосовану зміну.

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 записує байти PNG у стандартний вивід. Перенаправте їх у файл. Запитаний діапазон буде виділено, а звичайні вікна й збережені налаштування не зміняться. CLI експортує PNG, а не PDF.

popCalendar --export --start 2027-01-01 --end 2027-12-31 --calendar-set SET_UUID --plans PLAN_UUID --events > calendar.png
До змісту

Результати та помилки

Команди керування типово чекають прийняття до 60 секунд. --wait необов'язковий. --no-wait підтверджує лише доставку, не поєднується з --timeout і не застосовується до вибору дат, даних або діагностики. Прийняття не означає, що завантаження подій завершилося.

Команди даних повертають JSON. Із --json успіх або помилка є одним об'єктом JSON у стандартному виводі. Помилки містять errorCode, message і exitCode. Без --json помилки надходять у стандартний вивід помилок. --export повертає байти зображення й не підтримує --json.

{"version":1,"status":"error","errorCode":"invalid_arguments","message":"Unknown option --example.","exitCode":64,"command":"open"}
Код завершенняДія
0Успіх
2Вибір скасовано
3Час очікування минув
4Не вдалося запустити програму або встановити зв'язок
5Програма відхилила запит
64Неправильна команда або аргументи
70Внутрішня помилка або помилка каналу відповіді
128 + signalПерервано сигналом, зокрема 130 для Control-C
До змісту

Діагностика з'єднання

--doctor може запустити програму у фоні. Типовий час очікування становить десять секунд. Команда не змінює дозволи й не повертає вміст календаря. Успішна JSON-діагностика міститься в result.diagnostics із connection зі значенням connected і permissionSource зі значенням app. Невдалі перевірки містять об'єкт diagnostics верхнього рівня з локальними дозволами, які можуть відрізнятися від незбереженого стану програми, що не відповідає.

popCalendar --doctor --json
До змісту

Вміст і геометрія

Команда або параметрДія
--presentationТипово window, також popup або fullscreen. Перед зміною способу показу закрийте активний сеанс.
--modemonth, two-months, year, two-years, month-year або month-two-years. Типово year.
--dateГригоріанська дата YYYY-MM-DD у часовому поясі програми. Типово перша дата діапазону або сьогодні.
--start, --endМежі YYYY-MM-DD включно. Укажіть обидві, причому start не пізніше за end.
--clear-selectionОчистити вибір дат. Не можна поєднувати з --start і --end.
--calendar-setUUID збереженого набору або current для копіювання активного фільтра. Отримуйте ID через CLI чи Швидкі команди. Невідомі ID відхиляються.
--displayЛише для повноекранного показу. current використовує дисплей під вказівником, main головний дисплей, або вкажіть UUID. Від'єднаний дисплей замінюється доступним.
--width, --heightРозміри вмісту в логічних точках, кожен від 240 до 8192. Укажіть обидва. Спливні вікна зберігають запитаний розмір із першого видимого кадру. Звичайні вікна зі змінним розміром можуть збільшуватися до мінімального читабельного розміру. Межі екрана мають пріоритет. CLI також приймає --size WIDTHxHEIGHT.
--anchorПрямокутник прив'язки панелі як x,y,width,height у глобальних координатах екрана. Не поєднується з x і y.
--x, --yЯвна позиція замість прив'язки. Укажіть обидві координати. Панель із явною позицією не має стрілки.
--coordinatesappkit починається в нижньому лівому куті головного екрана. top-left відлічує вниз від верхнього лівого. Додаткові дисплеї можуть мати від'ємні координати. Значення задаються в пунктах, а не пікселях.
--arrowauto, top, bottom, left, right або none. Називає край панелі зі стрілкою. Розташування може змінитися, щоб панель залишалася видимою.
--callbackЗареєстрована власна схема URL для повернення явно підтверджених дат.

CLI використовує ті самі назви з префіксом --, крім selection=clear, що стає --clear-selection. Повноекранний показ відхиляє всі параметри геометрії, крім display. Невідомі чи дубльовані параметри, неправильні дати та URL понад 16 KiB відхиляються цілком.

До змісту