Gogcli Knowledge

gogcli Knowledge

Google Suite CLI (gogcli/gog) の仕様と使い方に関する包括的な知識を提供するスキル。

概要

gogcli は Google のサービス群（Gmail、Calendar、Drive、Contacts、Tasks、Sheets、Docs、Chat、Classroom 等）をターミナルから操作するための CLI ツール。JSON ファースト出力、マルチアカウント対応、最小権限認証を備える。

対応サービス

インストール方法

Homebrew（推奨）

brew install steipete/tap/gogcli

ソースからビルド

git clone https://github.com/steipete/gogcli.git
cd gogcli
make
./bin/gog --help

ヘルプの確認

gog --help                        # トップレベルコマンド一覧
gog <group> --help                # サブコマンドヘルプ
GOG_HELP=full gog --help          # 全コマンド展開表示

認証設定

gogcli は OAuth2 で Google API にアクセスする。

OAuth2 クイックスタート

# 1. Google Cloud Console で OAuth2 クライアント資格情報を作成
#    - Desktop app タイプで作成
#    - JSON ファイルをダウンロード

# 2. 資格情報を保存
gog auth credentials ~/Downloads/client_secret_....json

# 3. アカウントを認証（ブラウザが開く）
gog auth add you@gmail.com

# 4. テスト
export GOG_ACCOUNT=you@gmail.com
gog gmail labels list

マルチアカウント

# 複数アカウントの認証
gog auth add personal@gmail.com
gog auth add work@company.com

# アカウント一覧
gog auth list
gog auth list --check             # トークン有効性確認

# アカウント切り替え
gog gmail search 'is:unread' --account personal@gmail.com
gog gmail search 'is:unread' --account work@company.com

# デフォルトアカウント設定
export GOG_ACCOUNT=work@company.com

# エイリアス設定
gog auth alias set work work@company.com
gog gmail search 'is:unread' --account work

マルチ OAuth クライアント

# 別のクライアントで資格情報を保存
gog --client work auth credentials ~/Downloads/work.json

# ドメインマッピング（自動選択）
gog --client work auth credentials ~/Downloads/work.json --domain example.com

# クライアント一覧
gog auth credentials list

クライアント選択順序:

1. --client / GOG_CLIENT フラグ
2. account_clients 設定（email -> client）
3. client_domains 設定（domain -> client）
4. メールドメインと同名の credentials ファイル
5. default

サービスアカウント（Workspace のみ）

ドメイン全体の委任（domain-wide delegation）によるユーザー偽装:

# サービスアカウントキーを設定
gog auth service-account set you@yourdomain.com --key ~/Downloads/service-account.json

# 確認
gog --account you@yourdomain.com auth status
gog auth list

サービススコープ

# 特定サービスのみ認証
gog auth add you@gmail.com --services drive,calendar

# 読み取り専用
gog auth add you@gmail.com --services drive,calendar --readonly

# Drive スコープ制御
gog auth add you@gmail.com --services drive --drive-scope full      # フルアクセス
gog auth add you@gmail.com --services drive --drive-scope readonly  # 読み取り専用
gog auth add you@gmail.com --services drive --drive-scope file      # 自アプリファイルのみ

# スコープ追加時（再認証が必要な場合）
gog auth add you@gmail.com --services sheets --force-consent

キーリングバックエンド

# バックエンド設定
gog auth keyring file
gog auth keyring keychain
gog auth keyring auto

# 現在のバックエンド確認
gog auth keyring

# CI/非インタラクティブ環境
export GOG_KEYRING_BACKEND=file
export GOG_KEYRING_PASSWORD='...'
gog --no-input auth status

認証状態確認

gog auth status                   # 現在のアカウントの認証状態
gog auth services                 # 利用可能なサービスとスコープ一覧
gog auth list                     # 保存済みアカウント一覧
gog auth list --check             # トークン有効性検証
gog auth remove <email>           # アカウント削除

コマンド体系

グローバルフラグ

Gmail

# 検索
gog gmail search 'newer_than:7d' --max 10
gog gmail messages search 'newer_than:7d' --max 10 --include-body

# スレッド・メッセージ取得
gog gmail thread get <threadId>
gog gmail thread get <threadId> --download --out-dir ./attachments
gog gmail get <messageId>
gog gmail get <messageId> --format metadata
gog gmail url <threadId>

# スレッドラベル操作
gog gmail thread modify <threadId> --add STARRED --remove INBOX

# 送信
gog gmail send --to a@b.com --subject "Hi" --body "Hello"
gog gmail send --to a@b.com --subject "Hi" --body-file ./message.txt
gog gmail send --to a@b.com --subject "Hi" --body-html "<p>Hello</p>"

# 下書き
gog gmail drafts list
gog gmail drafts create --subject "Draft" --body "Body"
gog gmail drafts send <draftId>

# ラベル
gog gmail labels list
gog gmail labels get INBOX --json
gog gmail labels create "My Label"

# バッチ操作
gog gmail batch delete <messageId> <messageId>
gog gmail batch modify <messageId> <messageId> --add STARRED

# フィルタ
gog gmail filters list
gog gmail filters create --from 'noreply@example.com' --add-label 'Notifications'

# 設定
gog gmail autoforward get
gog gmail vacation get
gog gmail vacation enable --subject "Out of office" --message "..."
gog gmail sendas list
gog gmail delegates list

# Watch (Pub/Sub)
gog gmail watch start --topic projects/<p>/topics/<t> --label INBOX
gog gmail history --since <historyId>

メール追跡

# 追跡セットアップ
gog gmail track setup --worker-url https://gog-email-tracker.<acct>.workers.dev

# 追跡付き送信
gog gmail send --to a@b.com --subject "Hi" --body-html "<p>Hello</p>" --track

# 開封確認
gog gmail track opens <tracking_id>
gog gmail track opens --to recipient@example.com
gog gmail track status

Calendar

# カレンダー一覧
gog calendar calendars
gog calendar colors

# イベント取得
gog calendar events <calendarId> --today
gog calendar events <calendarId> --tomorrow
gog calendar events <calendarId> --week
gog calendar events <calendarId> --days 3
gog calendar events <calendarId> --from today --to friday
gog calendar events --all
gog calendar event <calendarId> <eventId>
gog calendar search "meeting" --today

# イベント作成
gog calendar create <calendarId> \
  --summary "Meeting" \
  --from 2025-01-15T10:00:00Z \
  --to 2025-01-15T11:00:00Z \
  --attendees "alice@example.com,bob@example.com" \
  --location "Zoom"

# イベント更新
gog calendar update <calendarId> <eventId> \
  --summary "Updated" \
  --send-updates all

# 出席者追加（既存を保持）
gog calendar update <calendarId> <eventId> \
  --add-attendee "alice@example.com"

# 繰り返し + リマインダー
gog calendar create <calendarId> \
  --summary "Payment" \
  --from 2025-02-11T09:00:00-03:00 \
  --to 2025-02-11T09:15:00-03:00 \
  --rrule "RRULE:FREQ=MONTHLY;BYMONTHDAY=11" \
  --reminder "email:3d" \
  --reminder "popup:30m"

# 特殊イベント
gog calendar focus-time --from ... --to ...
gog calendar out-of-office --from ... --to ... --all-day
gog calendar working-location --type office --office-label "HQ" --from ... --to ...

# 削除
gog calendar delete <calendarId> <eventId>

# 招待応答
gog calendar respond <calendarId> <eventId> --status accepted
gog calendar respond <calendarId> <eventId> --status declined
gog calendar propose-time <calendarId> <eventId>

# 空き状況
gog calendar freebusy --calendars "primary,work@example.com" \
  --from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z
gog calendar conflicts --calendars "primary" --today

# チームカレンダー（Workspace + Cloud Identity API）
gog calendar team <group-email> --today
gog calendar team <group-email> --freebusy

Chat（Workspace のみ）

# スペース
gog chat spaces list
gog chat spaces find "Engineering"
gog chat spaces create "Engineering" --member alice@company.com

# メッセージ
gog chat messages list spaces/<spaceId> --max 5
gog chat messages list spaces/<spaceId> --unread
gog chat messages send spaces/<spaceId> --text "Hello"

# スレッド
gog chat threads list spaces/<spaceId>

# DM
gog chat dm space user@company.com
gog chat dm send user@company.com --text "ping"

Classroom（Workspace for Education）

# コース
gog classroom courses list
gog classroom courses get <courseId>
gog classroom courses create --name "Math 101"

# 名簿
gog classroom roster <courseId>
gog classroom students add <courseId> <userId>

# 課題
gog classroom coursework list <courseId>
gog classroom coursework create <courseId> --title "Homework 1" --type ASSIGNMENT --state PUBLISHED

# 提出物・成績
gog classroom submissions list <courseId> <courseworkId>
gog classroom submissions grade <courseId> <courseworkId> <submissionId> --grade 85

# お知らせ・トピック
gog classroom announcements list <courseId>
gog classroom topics list <courseId>

Drive

# 一覧・検索
gog drive ls --max 20
gog drive ls --parent <folderId>
gog drive search "invoice" --max 20
gog drive get <fileId>
gog drive url <fileId>

# アップロード・ダウンロード
gog drive upload ./path/to/file --parent <folderId>
gog drive download <fileId> --out ./downloaded.bin
gog drive download <fileId> --format pdf --out ./exported.pdf

# フォルダ操作
gog drive mkdir "New Folder" --parent <parentFolderId>
gog drive rename <fileId> "New Name"
gog drive move <fileId> --parent <destinationFolderId>
gog drive delete <fileId>
gog drive copy <fileId> "Copy Name"

# 権限
gog drive permissions <fileId>
gog drive share <fileId> --to user --email user@example.com --role reader
gog drive unshare <fileId> --permission-id <permissionId>

# 共有ドライブ
gog drive drives --max 100

Docs / Slides

# Docs
gog docs info <docId>
gog docs cat <docId> --max-bytes 10000
gog docs create "My Doc"
gog docs copy <docId> "My Doc Copy"
gog docs export <docId> --format pdf --out ./doc.pdf

# Slides
gog slides info <presentationId>
gog slides create "My Deck"
gog slides copy <presentationId> "My Deck Copy"
gog slides export <presentationId> --format pptx --out ./deck.pptx

Sheets

# メタデータ・読み取り
gog sheets metadata <spreadsheetId>
gog sheets get <spreadsheetId> 'Sheet1!A1:B10'

# 書き込み
gog sheets update <spreadsheetId> 'A1' 'val1|val2,val3|val4'
gog sheets update <spreadsheetId> 'A1' --values-json '[["a","b"],["c","d"]]'
gog sheets append <spreadsheetId> 'Sheet1!A:C' 'new|row|data'
gog sheets clear <spreadsheetId> 'Sheet1!A1:B10'

# フォーマット
gog sheets format <spreadsheetId> 'Sheet1!A1:B2' \
  --format-json '{"textFormat":{"bold":true}}' \
  --format-fields 'userEnteredFormat.textFormat.bold'

# 作成・エクスポート
gog sheets create "My Spreadsheet" --sheets "Sheet1,Sheet2"
gog sheets export <spreadsheetId> --format pdf --out ./sheet.pdf
gog sheets copy <spreadsheetId> "My Sheet Copy"

Contacts

# 個人連絡先
gog contacts list --max 50
gog contacts search "Ada" --max 50
gog contacts get user@example.com
gog contacts create --given-name "John" --family-name "Doe" --email "john@example.com"
gog contacts update people/<resourceName> --given-name "Jane"
gog contacts delete people/<resourceName>

# その他の連絡先
gog contacts other list --max 50
gog contacts other search "John"

# Workspace ディレクトリ
gog contacts directory list --max 50
gog contacts directory search "Jane"

Tasks

# タスクリスト
gog tasks lists --max 50
gog tasks lists create <title>

# タスク操作
gog tasks list <tasklistId> --max 50
gog tasks get <tasklistId> <taskId>
gog tasks add <tasklistId> --title "Task title"
gog tasks add <tasklistId> --title "Weekly" --due 2025-02-01 --repeat weekly --repeat-count 4
gog tasks update <tasklistId> <taskId> --title "New title"
gog tasks done <tasklistId> <taskId>
gog tasks undo <tasklistId> <taskId>
gog tasks delete <tasklistId> <taskId>
gog tasks clear <tasklistId>

People

gog people me
gog people get people/<userId>
gog people search "Ada Lovelace" --max 5
gog people relations
gog people relations people/<userId> --type manager

Groups（Workspace のみ）

gog groups list
gog groups members engineering@company.com

Keep（Workspace のみ）

gog keep list --account you@yourdomain.com
gog keep get <noteId> --account you@yourdomain.com
gog keep search <query> --account you@yourdomain.com
gog keep attachment <attachmentName> --out ./attachment.bin

Time

gog time now
gog time now --timezone UTC

Config

gog config path
gog config list
gog config keys
gog config get default_timezone
gog config set default_timezone UTC
gog config unset default_timezone

出力形式

# JSON 出力でパイプ処理
gog --json drive ls --max 5 | jq '.files[] | select(.mimeType=="application/pdf")'

# Calendar JSON には曜日フィールドが追加される
gog calendar get <calendarId> <eventId> --json
# startDayOfWeek, endDayOfWeek フィールドが含まれる

• データは stdout、エラー・進捗は stderr に出力
• カラーは TTY 接続時のみ自動有効（--json, --plain では無効）

環境変数

設定ファイル

形式: JSON5（コメント、末尾カンマ対応）

パス:

• macOS: ~/Library/Application Support/gogcli/config.json
• Linux: ~/.config/gogcli/config.json
• Windows: %AppData%\\gogcli\\config.json

{
  keyring_backend: "file",
  default_timezone: "UTC",
  account_aliases: {
    work: "work@company.com",
    personal: "me@gmail.com",
  },
  account_clients: {
    "work@company.com": "work",
  },
  client_domains: {
    "example.com": "work",
  },
}

典型的なワークフロー

メール検索と添付ファイルダウンロード

gog gmail search 'newer_than:7d has:attachment' --max 10
gog gmail thread get <threadId> --download --out-dir ./attachments

カレンダーイベント作成

# 空き状況確認
gog calendar freebusy --calendars "primary" \
  --from 2025-01-15T00:00:00Z --to 2025-01-16T00:00:00Z

# イベント作成
gog calendar create primary \
  --summary "Team Standup" \
  --from 2025-01-15T10:00:00Z --to 2025-01-15T10:30:00Z \
  --attendees "alice@example.com,bob@example.com"

Drive ファイル検索とダウンロード

gog --json drive search "invoice filetype:pdf" --max 20 | \
  jq -r '.files[] | .id' | \
  while read fileId; do
    gog drive download "$fileId"
  done

Sheets へのデータ書き込み

# CSV から書き込み
cat data.csv | tr ',' '|' | gog sheets update <spreadsheetId> 'Sheet1!A1'

# JSON 形式で書き込み
gog sheets update <spreadsheetId> 'A1' --values-json '[["a","b"],["c","d"]]'

マルチアカウント運用

# エイリアス設定
gog auth alias set personal personal@gmail.com
gog auth alias set work work@company.com

# 使い分け
gog gmail search 'is:unread' --account personal
gog gmail search 'is:unread' --account work

サンドボックス実行（エージェント向け）

# calendar と tasks のみ許可
export GOG_ENABLE_COMMANDS=calendar,tasks
gog calendar events primary --today
gog tasks list <tasklistId>

シェル補完

# Bash
gog completion bash > $(brew --prefix)/etc/bash_completion.d/gog

# Zsh
gog completion zsh > "${fpath[1]}/_gog"

# Fish
gog completion fish > ~/.config/fish/completions/gog.fish

# PowerShell
gog completion powershell | Out-String | Invoke-Expression

セキュリティ

資格情報ストレージ

• macOS: Keychain Access
• Linux: Secret Service (GNOME Keyring, KWallet)
• Windows: Credential Manager
• フォールバック: 暗号化ファイル（GOG_KEYRING_BACKEND=file）

ベストプラクティス

• OAuth クライアント資格情報をバージョン管理にコミットしない
• 開発と本番で異なる OAuth クライアントを使用
• 不要なアカウントは gog auth remove で削除
• トークン漏洩の疑いがある場合は --force-consent で再認証

FAQ

Q: どの Google アカウントが使えますか？

A: 個人の Google アカウント（@gmail.com）と Google Workspace アカウントの両方に対応。ただし Chat、Groups、Keep、Classroom は Workspace アカウントが必要。

Q: OAuth2 の設定手順は？

A: Google Cloud Console でプロジェクトを作成し、必要な API を有効化、OAuth2 クライアント（Desktop app タイプ）を作成してJSON をダウンロード。gog auth credentials <path> で保存後、gog auth add <email> で認証。

Q: CI/CD 環境で使えますか？

A: はい。GOG_KEYRING_BACKEND=file と GOG_KEYRING_PASSWORD を設定し、--no-input フラグで非インタラクティブ実行が可能。

Q: 複数の Google Cloud プロジェクトを使い分けられますか？

A: はい。--client フラグまたは GOG_CLIENT 環境変数で名前付き OAuth クライアントを選択可能。ドメインマッピングによる自動選択も対応。

Q: コマンドを制限できますか？

A: はい。--enable-commands フラグまたは GOG_ENABLE_COMMANDS 環境変数でトップレベルコマンドの許可リストを設定可能。エージェント・サンドボックス実行に最適。

Q: JSON 出力はどのコマンドで使えますか？

A: 全コマンドで --json フラグが使用可能。データは stdout、エラーは stderr に出力されるため、パイプ処理が安全に行える。