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 you@example.com --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>   # アカウント選択
--client <name>                    # 名前付き OAuth クライアント/トークンバケット
--access-token <token>             # 直接短期トークン; GOG_ACCESS_TOKEN も可
--json, -j                         # マシン可読 JSON
--plain, -p                        # 安定した TSV
--results-only                     # JSON プライマリ結果のみ
--select <fields>                  # ベストエフォート JSON プロジェクション
--dry-run, -n                      # サポートされている書き込みプレビュー
--force, -y                        # 確認をスキップ
--no-input                         # プロンプトしない
--enable-commands <csv>            # トップレベルまたはドット記法コマンドのホワイトリスト
--disable-commands <csv>           # トップレベルまたはドット記法コマンドのブラックリスト
--gmail-no-send                    # Gmail 送信操作をブロック
--verbose, -v                      # デバッグログ

便利なコマンドエイリアス:

gog send ...             # gog gmail send のエイリアス
gog ls                   # gog drive ls のエイリアス
gog search "budget"      # gog drive search のエイリアス
gog download <fileId>    # gog drive download のエイリアス
gog upload ./file.pdf    # gog drive upload のエイリアス
gog me                   # gog people me のエイリアス
gog status               # gog auth status のエイリアス
gog open <id-or-url>     # ベストエフォート Google ウェブ URL、オフライン

高い価値のワークフロー

アカウント選択

gog auth alias set work you@company.com
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 you@company.com --services gmail,calendar

Gmail

gog --json gmail search 'is:unread newer_than:7d' | jq -r '.threads[].id'
gog gmail messages search 'from:alice@example.com 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 user@example.com --subject "Hello" --body-file ./body.txt
gog gmail forward <messageId> --to user@example.com --note "FYI"

転送、自動返信、watch/Pub/Sub、フィルター、委譲、send-as、ラベル色、バッチ操作、トラッキングについては、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 "alice@example.com,bob@example.com" --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 editor@example.com --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 engineering@example.com
gog admin users list --domain example.com
gog keep search "receipt"

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

スクリプティングパターン

# まず形状を検査する
gog --json gmail search 'is:unread' --max 3 | jq .

# 利用可能な場合はページネーション/全ページを使用
gog --json calendar events primary --from today --to tomorrow --all-pages

# サポートされているリストコマンドに結果がない場合はきれいに失敗
gog --json calendar events primary --query "unlikely query" --fail-empty

# 出力を確認した後、xargs でバッチ処理
gog --json gmail search 'older_than:1y label:newsletter' --max 200 | \
  jq -r '.threads[].id' | \
  xargs -n 50 gog gmail labels modify --remove INBOX

# エージェント安全なコマンドサーフェス
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