google-calendar

Google Calendar（gws）

このスキルは、gws 0.22.5 専用です。

実行ファイルの場所を確認する

必ずこのスキルに同梱されているものを使用してください。PATH 上にあるだけの gws は、別のバージョンである可能性があるため使用しないでください。セッションごとに一度、次の手順で場所を解決します。

1. プラットフォームのディレクトリを特定します。macOS では uname -m を実行し（arm64 → darwin-arm64、x86_64 → darwin-x64）、Windows では win32-x64 を使用します。
2. scripts/bin/<platform>/gws をこのドキュメントのディレクトリを基準に解決します。Windows ではファイル名は gws.exe です。以下のすべてのコマンドには、その絶対パスを使用します。

このパッケージには macOS と Windows のビルドのみが含まれています。それ以外のプラットフォームでは、別のインストール先を探さず、Google Calendar は利用できないと伝えてください。

以下の例では読みやすさのため、コマンドを名前だけで記載しています。実行時は必ず、解決した絶対パスを使用してください。

ファイルが見つからない場合は、Google Calendar の準備がまだできていないと伝えてください。アカウントの問題やコネクタの不具合として説明してはいけません。

Cola のように話す

これらのルールは、ユーザーへの説明に適用されます。実行するコマンドが変わることはありません。

• 製品に関する言葉は使用してかまいません。 設定、認可、接続、アカウント、予定、アプリ専用パスワードなど、ユーザーがどの段階にいるのか常にわかるようにしてください。
• 実装の詳細をユーザーに伝えてはいけません。 ツール名、CLI フラグ、設定ファイル、プロトコル、PATH、生のコマンド、生のエラー出力は伝えないでください。目標に沿って説明し（「カレンダーを確認しています」など）、失敗した場合は、次に取るべき手順を明確に一つ伝えてください。結果はユーザーにとってわかりやすい言葉で伝えてください。

使用シーン

• 予定の確認：「明日の Google カレンダーの予定を見て」「今週、午後を通して空いている日はある？」
• 予定の作成と変更：「木曜の午後に1時間のレビュー会議を設定して、Alice を招待して」「週次ミーティングを10時に変更して」
• 予定の要約：「来週の予定を議題としてまとめて」

リクエストでプロバイダーが指定されていない場合。 複数のカレンダースキルがインストールされていることがあります。「予定を確認して」だけでは、どのアカウントを参照するのか特定できません。接続済みのカレンダーがこれだけの場合、または会話の中ですでに Google Calendar を使うことが決まっている場合に限り、確認せずにこのスキルを使用してください。それ以外の場合は、どのカレンダーを使うのか尋ねてください。ユーザーが指定していないアカウントの接続フローを開始してはいけません。

このインストールで利用できるのはカレンダー機能のみです。認可の対象は Google Calendar に限られ、他の Google サービス（gmail、drive、sheets、docs、tasks など）は権限エラーになります。これらのサービスを試したり、利用可能なものとして提案したりしないでください。

認可

OAuth は、カレンダー専用のスコープ（calendar.events と読み取り専用のカレンダーリスト）を使って Cola が管理します。実行する gws コマンドには、認証情報がすでに設定されています。

• gws auth login やその他の対話型認証フローは実行せず、GOOGLE_APPLICATION_CREDENTIALS も設定しないでください。 認可は、ユーザーが Cola のアプリセンターで行います。
• コマンドが認可または権限エラーで失敗した場合は、Cola のスキル設定で Google Calendar アプリを開き、認可を完了または更新するようユーザーに案内してください。何度も繰り返し再試行しないでください。

スコープの範囲

付与されるスコープで可能なのは、次の操作に限られます。

• events — カレンダーイベントの読み取りと書き込み
• calendarList — 読み取り専用（list、get）

対象外の操作（失敗するため、呼び出さないでください）：カレンダーの acl、カレンダーの作成・削除（calendars insert/delete/clear）、settings、channels／watch のサブスクリプション、およびカレンダー以外のすべてのサービス。

ヘルパーコマンド

予定を表示（読み取り専用）

gws calendar +agenda --timezone <IANA>

フラグ	説明
--today	今日の予定を表示
--tomorrow	明日の予定を表示
--week	今週の予定を表示
--days <N>	表示する先の日数
--calendar <NAME_OR_ID>	特定のカレンダーに絞り込む
--timezone <IANA>	タイムゾーンを上書きします（例：Asia/Shanghai）。必ず指定してください — 以下を参照してください

gws calendar +agenda --today --timezone 'Asia/Shanghai'
gws calendar +agenda --week --format table --timezone 'Asia/Shanghai'
gws calendar +agenda --days 3 --calendar 'Work' --timezone 'Asia/Shanghai'

読み取り専用 — 予定は変更されません。デフォルトでは、すべてのカレンダーを検索します。

--timezone は必ず指定してください。このヘルパーのデフォルト設定は settings からアカウントのタイムゾーンを読み取りますが、このインストール環境ではそのスコープが除外されているため、警告なしにマシンのローカルタイムゾーンにフォールバックします。カレンダーとは異なるタイムゾーンのマシンでは、--today と --week が誤った日の範囲を検索することになります。ユーザーにタイムゾーンを確認するか、予定自体のタイムゾーンを使用し、明示的に指定してください。

予定を作成

gws calendar +insert --summary <TEXT> --start <TIME> --end <TIME>

フラグ	必須	説明
--summary	✓	予定のタイトル
--start	✓	開始時刻（RFC 3339、例：2026-06-17T09:00:00+08:00）
--end	✓	終了時刻（RFC 3339）
--calendar	—	カレンダー ID（デフォルト：primary）
--location	—	予定の場所
--description	—	予定の説明／本文
--attendee	—	参加者のメールアドレス（複数回指定可能）。参加者には通知されません — 以下を参照してください
--meet	—	Google Meet のリンクを追加

gws calendar +insert --summary 'Standup' --start '2026-06-17T09:00:00+08:00' --end '2026-06-17T09:30:00+08:00'
gws calendar +insert --summary 'Review' --start ... --end ... --attendee [email protected] --meet

注意

これは書き込みコマンドです — 実行する前にユーザーに確認してください。

+insert では参加者に通知されません。ヘルパーは Calendar API の sendUpdates パラメーターを設定しません。このパラメーターのデフォルトは通知を送信しないため、ゲストは予定に追加されますが、招待は届きません。ユーザーが誰かを招待する意図の場合は、代わりにそのパラメーターを指定したリソースレベルのコマンドで予定を作成し、招待が送信されたことをユーザーに伝えてください。

gws calendar events insert \
  --params '{"calendarId":"primary","sendUpdates":"all"}' \
  --json '{"summary":"Review","start":{"dateTime":"2026-06-17T09:00:00+08:00"},"end":{"dateTime":"2026-06-17T10:00:00+08:00"},"attendees":[{"email":"[email protected]"}]}'

+insert --meet は Meet のリンクを自動的に追加しますが、このリソースレベルの形式では追加されません — カンファレンスを明示的にリクエストしてください。そうしないと、招待に参加方法が含まれないまま送信されます。

gws calendar events insert \
  --params '{"calendarId":"primary","sendUpdates":"all","conferenceDataVersion":1}' \
  --json '{"summary":"Review","start":{"dateTime":"2026-06-17T09:00:00+08:00"},"end":{"dateTime":"2026-06-17T10:00:00+08:00"},"attendees":[{"email":"[email protected]"}],"conferenceData":{"createRequest":{"requestId":"<unique-string>","conferenceSolutionKey":{"type":"hangoutsMeet"}}}}'

API リソース（スコープ内）

gws calendar <resource> <method> [flags]

events

• list — カレンダー上の予定（--params '{"calendarId":"primary","timeMin":"...","timeMax":"...","singleEvents":true,"orderBy":"startTime"}'）
• get — ID で予定を 1 件取得
• instances — 繰り返し予定のインスタンス
• insert — 予定を作成（+insert を推奨）
• quickAdd — テキスト文字列から予定を作成
• patch — 予定を変更します。編集にはすべてこれを使用してください。予定に参加者がいる場合は、--params に "sendUpdates":"all" を追加して、ゲストに変更を知らせてください。デフォルトでは誰にも通知されないため、ゲストには古い時刻のまま表示されます
• update — 全体を置き換えます。本文に含まれていない参加者、繰り返し設定、リマインダー、場所、説明は削除されるため、イベント全体を取得してすべてのフィールドを引き継いだ後にのみ使用してください
• delete — 予定を削除します。参加者がいる場合は "sendUpdates":"all" も指定してください。そうしないと、主催者がすでにキャンセルした会議がゲスト側に残ります

calendarList（読み取り専用）

• list — ユーザーのカレンダーリスト上のカレンダー
• get — カレンダーリストのエントリを 1 件取得

メソッドのフラグ

フラグ	説明
--params '{"key": "val"}'	URL／クエリパラメーター
--json '{"key": "val"}'	リクエスト本文（POST/PATCH/PUT）
--format <FMT>	出力形式：json（デフォルト）、table、yaml、csv
--dry-run	API を呼び出さずにローカルで検証
--page-all	自動ページネーション（NDJSON 出力）
--page-limit <N>	--page-all 使用時の最大ページ数（デフォルト：10）

シェルが内部の二重引用符を解釈しないように、--params と --json の値は一重引用符で囲んでください。

コマンドを調べる

gws calendar --help
gws schema calendar.<resource>.<method>   # required params, types, defaults

--params と --json の作成には、gws schema の出力を使用してください。

セキュリティルール

• シークレット（トークン、認証情報ファイル）を直接出力することは絶対に避けてください。
• 書き込みコマンドまたは削除コマンドを実行する前に、必ずユーザーに確認してください。
• 破壊的な操作では、まず--dry-runを使用してください。
• オフセットを明示したRFC 3339形式の時刻を使用し、ユーザーのタイムゾーン（+agendaの--timezone）を尊重してください。