gog-cli

gogcli（gog）

gog は、Google サービス向けの高速でスクリプトに適した CLI です。JSON を優先し、複数のアカウント／OAuth クライアントをサポートし、エージェントや CI での使用に対する明示的な安全策を備えています。

正式なアップストリーム：https://github.com/steipete/gogcli

このスキルは、アップストリームの gog v0.13.0（2026-04-20）に合わせて更新されています。正確な構文が必要な場合は、gog <command> --help または gog schema --json を実行してください。コマンドの仕様は急速に変わるため、古いメモを好む方には少々厄介です。

運用ルール

• 確認やスクリプト作成には、gog --json ... | jq ... を優先してください。
• JSON より安定した TSV のほうが便利な場合に限り、--plain を使用してください。
• 変更を準備するときや、ユーザーの意図が曖昧な場合は、対応している変更操作で --dry-run を使用してください。
• 自動化では --no-input を使用し、コマンドがプロンプトを表示せずに失敗するようにしてください。
• --force は、ユーザーが破壊的操作／公開操作／送信操作／管理者操作を依頼した場合、または効果を明確に説明した後に限り使用してください。
• OAuth、同意、キーリング、Workspace の委任に関する問題を、黙って修復しないでください。ユーザーが実行すべき正確なコマンドを提示してください。
• ユーザーが明示的に依頼しない限り、トークンのエクスポート、シークレットの表示、公開共有の作成、代理人／転送先の追加、メールの送信、ユーザーの停止、データの完全削除は行わないでください。
• メールを送信してはならないエージェントの実行では、--gmail-no-send を追加するか、GOG_GMAIL_NO_SEND=1 を設定するか、gog config no-send set <account> を設定してください。

インストールと認証

brew install gogcli
gog auth credentials set ~/Downloads/client_secret_....json
gog auth add [email protected] --services gmail,calendar,drive
gog auth list --check

補足：

• Homebrew では現在 brew install gogcli を使用します。古い tap の例は廃止されています。
• gog auth add は、既定で --services user を使用します。タスクに必要なサービスを指定してください。
• --services all は後方互換性のための user の別名としてのみ受け付けられます。すべての API が必要な場合に使用しないでください。
• 最小権限を適用するには、--readonly、--drive-scope readonly|file|full、--gmail-scope readonly|full を使用してください。
• Keep と Admin には、Workspace のサービスアカウント／ドメイン全体の委任が必要です。Google Chat、Groups、ディレクトリ、Classroom にも Workspace による制限があります。
• ヘッドレス環境／CI では、--manual、--remote、--access-token、または GOG_AUTH_MODE=adc の使用を検討してください。

認証パターンの詳細は references/authentication.md を参照してください。

グローバルフラグ

--account, -a <email|alias|auto>   # account selection
--client <name>                    # named OAuth client/token bucket
--access-token <token>             # direct short-lived token; also GOG_ACCESS_TOKEN
--json, -j                         # machine-readable JSON
--plain, -p                        # stable TSV
--results-only                     # JSON primary result only
--select <fields>                  # best-effort JSON projection
--dry-run, -n                      # preview supported writes
--force, -y                        # skip confirmations
--no-input                         # never prompt
--enable-commands <csv>            # allowlist top-level or dotted commands
--disable-commands <csv>           # denylist top-level or dotted commands
--gmail-no-send                    # block Gmail send operations
--verbose, -v                      # debug logging

便利なコマンドの別名：

gog send ...             # alias for gog gmail send
gog ls                   # alias for gog drive ls
gog search "budget"      # alias for gog drive search
gog download <fileId>    # alias for gog drive download
gog upload ./file.pdf    # alias for gog drive upload
gog me                   # alias for gog people me
gog status               # alias for gog auth status
gog open <id-or-url>     # best-effort Google web URL, offline

重要なワークフロー

アカウントの選択

gog auth alias set work [email protected]
gog --account work gmail search 'is:unread newer_than:2d'
GOG_ACCOUNT=work gog calendar events primary --today
gog --client work auth credentials set ~/Downloads/work-client.json
gog --client work auth add [email protected] --services gmail,calendar

Gmail

gog --json gmail search 'is:unread newer_than:7d' | jq -r '.threads[].id'
gog gmail messages search 'from:[email protected] has:attachment' --include-body
gog gmail messages search 'subject:report newer_than:30d' --full
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail labels modify <threadId> --add Project --remove INBOX
gog gmail messages modify <messageId> --add STARRED
gog gmail send --to [email protected] --subject "Hello" --body-file ./body.txt
gog gmail forward <messageId> --to [email protected] --note "FYI"

転送、自動返信、watch／Pub/Sub、フィルター、代理人、送信元、ラベルの色、バッチ操作、トラッキングについては、references/gmail.md を参照してください。

Calendar

gog calendar calendars
gog calendar events primary --today --weekday
gog calendar events --all --from "2026-04-25T00:00:00+02:00" --to "2026-04-26T00:00:00+02:00"
gog calendar freebusy --cal primary --from "2026-04-25T09:00:00+02:00" --to "2026-04-25T17:00:00+02:00"
gog calendar create primary --summary "Planning" --from "2026-04-25T14:00:00+02:00" --to "2026-04-25T14:30:00+02:00" --attendees "[email protected],[email protected]" --with-meet
gog calendar respond primary <eventId> --status accepted --send-updates all

生成する日時には、タイムゾーンオフセットを含む RFC3339 を使用してください。別名、登録、セカンダリカレンダー、拡張プロパティ、集中作業時間、OOO、勤務場所、チームカレンダー、競合の検出については、references/calendar.md を参照してください。

Drive、Docs、Sheets、Slides、Forms、Apps Script

gog drive search "invoice filetype:pdf" --max 20
gog drive upload ./report.md --convert-to doc --parent <folderId>
gog drive upload ./deck.pdf --replace <fileId> --name "Board Deck.pdf"
gog drive share <fileId> --to user --email [email protected] --role commenter
gog docs write <docId> --file ./brief.md --replace --markdown
gog docs sed <docId> 's/status/{b c=green}approved/g' --dry-run
gog sheets update <spreadsheetId> 'Sheet1!A1' '[["Name","Score"],["Ada",98]]'
gog sheets chart list <spreadsheetId>
gog slides thumbnail <presentationId> <slideId> --out ./slide.png
gog forms responses list <formId> --max 20
gog appscript run <scriptId> myFunction --params '["arg1", 123]'

現在のファイル／コンテンツ関連コマンドについては、references/drive-docs.md を参照してください。Docs の sed フォーマットについては、references/sedmat.md を参照してください。

その他のサービス

gog contacts search "Ada"
gog tasks lists
gog tasks add <tasklistId> --title "Weekly review" --due "2026-04-27" --repeat weekly
gog chat messages send spaces/<spaceId> --text "Build complete"
gog groups members [email protected]
gog admin users list --domain example.com
gog keep search "receipt"

Chat、Classroom、Contacts、Tasks、People、Groups、Admin、Keep、時間ユーティリティについては、references/other-services.md を参照してください。

スクリプト作成のパターン

# Inspect shape first
gog --json gmail search 'is:unread' --max 3 | jq .

# Use pagination/all-pages where available
gog --json calendar events primary --from today --to tomorrow --all-pages

# Fail cleanly when a supported list command has no results
gog --json calendar events primary --query "unlikely query" --fail-empty

# Batch with xargs after checking output
gog --json gmail search 'older_than:1y label:newsletter' --max 200 | \
  jq -r '.threads[].id' | \
  xargs -n 50 gog gmail labels modify --remove INBOX

# Agent-safe command surface
GOG_ENABLE_COMMANDS=calendar.events,calendar.freebusy,tasks \
  gog --no-input --json calendar events primary --today

リファレンス一覧

• references/command-reference.md - gog schema --json から生成されたコマンド一覧
• references/authentication.md - OAuth クライアント、サービスアカウント、スコープ、キーリング、ヘッドレス認証
• references/configuration.md - 設定キー、環境変数、出力モード、安全スイッチ
• references/gmail.md - Gmail の検索、読み取り、送信、ラベル、設定、watch、トラッキング、自動返信
• references/calendar.md - Calendar の一覧表示、イベントの書き込み、スケジュール設定、特別なイベント、別名
• references/drive-docs.md - Drive、Docs、Sheets、Slides、Forms、Apps Script
• references/sedmat.md - Docs の sed／フォーマット DSL
• references/other-services.md - Chat、Classroom、Contacts、Tasks、People、Groups、Admin、Keep