gogcli-knowledge

name	gogcli-knowledge
description	Use when user asks about gogcli, gog CLI, Google CLI, Gmail CLI, Google Calendar CLI, Google Drive CLI, or Google Workspace CLI. Also use when user says gogcli について, Google CLI について, gog コマンド, Gmail 操作, カレンダー操作, ドライブ操作. Google Suite CLI (gogcli/gog) の仕様と使い方に関する知識を提供し、Gmail、Calendar、Drive、Contacts、Tasks、Sheets、Docs、Chat、Classroom、People、Groups、Keep の操作について回答する。
context	fork

gogcli Knowledge

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

概要

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

項目	内容
正式名称	gogcli
コマンド名	gog
GitHub リポジトリ	https://github.com/steipete/gogcli
ホームページ	https://gogcli.sh
開発言語	Go
ライセンス	MIT
作者	steipete (Peter Steinberger)

---

対応サービス

サービス	コマンドグループ	説明
Gmail	gog gmail	スレッド・メッセージ検索、送信、ラベル、フィルタ、委任、Watch (Pub/Sub)、メール追跡
Calendar	gog calendar	イベント CRUD、空き状況、チーム、招待、繰り返し、focus/OOO/working-location
Chat	gog chat	スペース、メッセージ、スレッド、DM（Workspace のみ）
Classroom	gog classroom	コース、名簿、課題、提出物、成績、お知らせ（Workspace for Education）
Drive	gog drive	ファイル一覧・検索・アップロード・ダウンロード、フォルダ、権限、共有ドライブ
Docs	gog docs	情報取得、テキスト抽出、作成、コピー、エクスポート
Slides	gog slides	情報取得、作成、コピー、エクスポート
Sheets	gog sheets	読み書き、フォーマット、作成、エクスポート
Contacts	gog contacts	個人連絡先、その他の連絡先、ディレクトリ（Workspace）
Tasks	gog tasks	タスクリスト管理、タスク CRUD、繰り返し
People	gog people	プロフィール、検索、リレーション
Groups	gog groups	グループ一覧、メンバー一覧（Workspace のみ）
Keep	gog keep	ノート一覧・取得・検索、添付ファイル（Workspace のみ、サービスアカウント必須）
Time	gog time	ローカル/UTC 時刻表示

---

インストール方法

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 [e-mail]

# 4. テスト
export GOG_ACCOUNT=[e-mail]
gog gmail labels list

マルチアカウント

# 複数アカウントの認証
gog auth add [e-mail]
gog auth add [e-mail]

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

# アカウント切り替え
gog gmail search 'is:unread' --account [e-mail]
gog gmail search 'is:unread' --account [e-mail]

# デフォルトアカウント設定
export GOG_ACCOUNT=[e-mail]

# エイリアス設定
gog auth alias set work [e-mail]
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 [e-mail] --key ~/Downloads/service-account.json

# 確認
gog --account [e-mail] auth status
gog auth list

サービススコープ

# 特定サービスのみ認証
gog auth add [e-mail] --services drive,calendar

# 読み取り専用
gog auth add [e-mail] --services drive,calendar --readonly

# Drive スコープ制御
gog auth add [e-mail] --services drive --drive-scope full      # フルアクセス
gog auth add [e-mail] --services drive --drive-scope readonly  # 読み取り専用
gog auth add [e-mail] --services drive --drive-scope file      # 自アプリファイルのみ

# スコープ追加時（再認証が必要な場合）
gog auth add [e-mail] --services sheets --force-consent

キーリングバックエンド

バックエンド	説明
auto	OS に最適なバックエンド（デフォルト）
keychain	macOS Keychain（推奨）
file	暗号化ファイル（CI/SSH 向け）

# バックエンド設定
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>           # アカウント削除

---

コマンド体系

グローバルフラグ

フラグ	説明
--account <email|alias|auto>	使用アカウント
--client <name>	OAuth クライアント名
--json	JSON 出力
--plain	TSV 出力（パイプ向け）
--color <auto|always|never>	カラーモード
--force	確認スキップ
--no-input	非インタラクティブモード
--verbose	詳細ログ
--enable-commands <csv>	コマンド許可リスト

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 [e-mail] --subject "Hi" --body "Hello"
gog gmail send --to [e-mail] --subject "Hi" --body-file ./message.txt
gog gmail send --to [e-mail] --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 '[e-mail]' --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 [e-mail] --subject "Hi" --body-html "<p>Hello</p>" --track

# 開封確認
gog gmail track opens <tracking_id>
gog gmail track opens --to [e-mail]
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 "[e-mail],[e-mail]" \
  --location "Zoom"

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

# 出席者追加（既存を保持）
gog calendar update <calendarId> <eventId> \
  --add-attendee "[e-mail]"

# 繰り返し + リマインダー
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,[e-mail]" \
  --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 [e-mail]

# メッセージ
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 [e-mail]
gog chat dm send [e-mail] --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 [e-mail] --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 [e-mail]
gog contacts create --given-name "John" --family-name "Doe" --email "[e-mail]"
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 [e-mail]

Keep（Workspace のみ）

gog keep list --account [e-mail]
gog keep get <noteId> --account [e-mail]
gog keep search <query> --account [e-mail]
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

---

出力形式

形式	フラグ	用途
テーブル	(デフォルト)	人間向け表示
TSV	--plain	パイプ処理向け（タブ区切り）
JSON	--json	スクリプティング・自動化向け

# 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 では無効）

---

環境変数

変数	説明
GOG_ACCOUNT	デフォルトアカウント（email またはエイリアス）
GOG_CLIENT	OAuth クライアント名
GOG_JSON	デフォルト JSON 出力
GOG_PLAIN	デフォルト plain 出力
GOG_COLOR	カラーモード: auto, always, never
GOG_TIMEZONE	出力タイムゾーン（IANA 名, UTC, local）
GOG_ENABLE_COMMANDS	コマンド許可リスト（カンマ区切り）
GOG_KEYRING_BACKEND	キーリングバックエンド: auto, keychain, file
GOG_KEYRING_PASSWORD	キーリングパスワード（CI/非インタラクティブ向け）

---

設定ファイル

形式: 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: "[e-mail]",
    personal: "[e-mail]",
  },
  account_clients: {
    "[e-mail]": "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 "[e-mail],[e-mail]"

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 [e-mail]
gog auth alias set work [e-mail]

# 使い分け
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 に出力されるため、パイプ処理が安全に行える。