オートメーションのドキュメント

コマンドラインリファレンス

Dockの代替アプリやその他のMacツールにpopCalendarを連携できます。CLIからカレンダーの表示、日付の選択、プランの管理、画像の書き出しを行えます。

このガイドはpopCalendar 1.3以降を対象としています。一部のアクションには、以下に記載する新しいシステムバージョンが必要です。

あなたのツールに充実したカレンダー体験を

Dockの代替アプリ、ランチャー、メニューバーユーティリティなど、あらゆるMacツールにpopCalendarを連携できます。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

レイアウトを指定しない場合、収まれば1年分、収まらなければ1か月分を表示します。対話モードは、レイアウトを指定するか期間を選択するまでウインドウサイズの変更に合わせて調整されます。パイプ、JSON、予定一覧のみの出力は、既定で1か月分です。

目次に戻る

予定、計画、稼働日

--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の日付、または今日から7日間を意味します。期間には両端の日付が含まれます。明示的な選択がない場合、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です。同じセッションを使うと、同じウインドウが更新されます。独立したウインドウには別の名前を使います。6種類すべての表示モードに対応しています。

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の操作スペースを作らずに1台のディスプレイ全体を使います。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 が返す ID に置き換えてください。REQUEST_UUID と NEW_REQUEST_UUID には異なる UUID を使ってください。必要な権限については、自動化の概要で説明しています。

コマンドまたはオプション動作
--helpすべてのコマンドとオプションのリファレンスを表示します。
--versionアプリのバージョンとビルドを表示します。
--capabilities [--json]アプリを開かずに、対応するコマンドと制限を返します。
--doctor [--json] [--timeout SECONDS]アプリの識別情報、権限、アプリとの通信を確認します。
--sets [--json]保存済みカレンダーセットの名前とIDを返します。
--sessions [--json]Macで開いている連携セッションのIDを返します。
--plans [--name SEARCH] [--id UUID] [--json]保存済みプラン、その範囲、繰り返し情報を返します。名前またはIDで絞り込めます。
--create-plan --name NAME --start YYYY-MM-DD --end YYYY-MM-DD [--request-id UUID]両端を含む日付範囲を名前付きで保存し、プランIDを返します。
--duplicate-plan --id UUID --name NAME [--request-id UUID]保存済みプランを別の名前で複製し、そのIDを返します。
--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指定した分数だけチャイムを一時停止します。最長7日間です。
--resume-chimes設定済みのチャイムのスケジュールと有効状態を維持して、一時停止を終了します。
--export --start YYYY-MM-DD --end YYYY-MM-DD [--calendar-set UUID] [--plans UUID,UUID] [--events]最大2暦年分のPNGを書き出します。指定した保存済みプランだけを含みます。イベントの丸印は指定した場合だけ含みます。

APIの日付はアプリのタイムゾーンでグレゴリオ暦のYYYY-MM-DDを使います。稼働日計算には有効な勤務スケジュールが必要です。日付の照会は10年まで、移動は2600稼働日までです。イベントの読み取りに失敗した場合は、休暇をゼロとして扱わずエラーを返します。

プランの作成や複製を再試行する場合は、同じリクエストUUIDと同じ内容を使います。再試行では既存のIDが返され、内容が異なる場合は失敗します。結果を編集または削除した後は、その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を使うと、成功または失敗は標準出力の1つの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シグナルによる中断。Control-Cの場合は130
目次に戻る

接続を診断する

--doctorは必要に応じてアプリをバックグラウンドで起動します。既定のタイムアウトは10秒です。権限を変更せず、カレンダーの内容も返しません。成功した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-set保存済みセットのUUID、または現在のフィルタをコピーする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以外の配置オプションを拒否します。不明または重複したパラメータ、不正な日付、16 KiBを超えるURLは全体が拒否されます。

目次に戻る