google-workspace

Google Workspace CLI (gws)

Google Workspace のすべてを扱える単一の CLI です。実行時に Google の Discovery Service を読み込むため、新しい API エンドポイントが自動的に利用可能になります。

前提条件

• $PATH に gws バイナリがあること（インストール：pnpm add -g @googleworkspace/cli）
• 認証済みであること：gws auth login（ブラウザー経由の OAuth）
• 認証状態：gws auth status

リファレンス

すべての gws スキルファイルは、上流の Gemini 拡張機能から次の場所にシンボリックリンクされています： ./gws-skills/

主なリファレンス：

• ./gws-skills/gws-shared/SKILL.md - 認証、グローバルフラグ、セキュリティルール
• ./gws-skills/gws-drive/SKILL.md - Drive のファイル／フォルダー操作
• ./gws-skills/gws-docs/SKILL.md - Google Docs の読み書き
• ./gws-skills/gws-docs-write/SKILL.md - Docs へのテキストの追記
• ./gws-skills/gws-sheets/SKILL.md - Sheets の操作
• ./gws-skills/gws-gmail/SKILL.md - Gmail の操作
• ./gws-skills/gws-calendar/SKILL.md - Calendar の操作
• ./CONTEXT.md - 基本的な構文と使用パターン

使ったことのないコマンドを実行する前に、該当するスキルファイルを読んでください。

基本構文

gws <service> <resource> [sub-resource] <method> [flags]

共通フラグ

フラグ	説明
--params '<JSON>'	URL／クエリパラメーター
--json '<JSON>'	リクエスト本文（POST/PUT/PATCH）
--fields '<MASK>'	レスポンスのフィールドを制限（コンテキストウィンドウの保護に重要）
--page-all	自動ページネーション（NDJSON 出力）
--upload <PATH>	マルチパートアップロード用ファイル
--output <PATH>	バイナリダウンロードの保存先
--dry-run	API を呼び出さずに検証

スキーマの確認

ペイロードの構造がわからない場合は、まずスキーマを確認してください：

gws schema <service>.<resource>.<method>
# Example: gws schema drive.files.list
# Example: gws schema docs.documents.batchUpdate

よく使うパターン

Drive - ファイルの一覧表示／検索

gws drive files list --params '{"q": "name contains \"Report\"", "pageSize": 10}' --fields "files(id,name,mimeType)"

Drive - フォルダーの作成

gws drive files create --json '{"name": "My Folder", "mimeType": "application/vnd.google-apps.folder"}'

Drive - ファイルをフォルダーに移動

gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID"}'

Drive - Google Doc をプレーンテキストとしてエクスポート

gws drive files export --params '{"fileId": "DOC_ID", "mimeType": "text/plain"}' --output /tmp/doc.txt

Docs - ドキュメントの読み取り

gws docs documents get --params '{"documentId": "DOC_ID", "fields": "title,body"}'

Docs - ドキュメントへの書き込み（batchUpdate）

テキストを挿入／置換する場合は、シェルのエスケープ処理を避けるため JSON ペイロードファイルを作成してください：

import json
payload = {
    "requests": [
        {"insertText": {"location": {"index": 1}, "text": "Hello world"}}
    ]
}
with open('/tmp/payload.json', 'w') as f:
    json.dump(payload, f)

gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json "$(cat /tmp/payload.json)"

Docs - テキストの追記（ヘルパー）

gws docs +write --document DOC_ID --text 'Text to append'

Sheets - セルの読み取り

gws sheets spreadsheets values get --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'

Gmail - メッセージの検索

gws gmail users messages list --params '{"userId": "me", "q": "from:[email protected]"}'

エージェントワークフローとバイブコーディング

• API の反復実行： 複雑な Workspace API ペイロードが最初の試行で成功するとは限りません。ペイロードを作成し、--dry-run フラグを付けて実行し、想定される変更を確認して、スキーマエラーを切り分けます。フィールドを一度に 1 つずつ修正し、ペイロードが有効になるまで再テストしてから、実際の変更を実行してください。
• バイブコーディング： 複雑な JSON ペイロードやスクリプトの手順はローカルファイルに保存し、Drive や Docs で取り消せない一括操作を実行する前にコミットしてください。

ルール

• コンテキストウィンドウの保護： 巨大な JSON レスポンスを避けるため、list/get では必ず --fields を使用してください
• まずドライラン： 破壊的な操作は実行前に --dry-run を使用してください
• 書き込みの確認： 書き込み／削除コマンドを実行する前にユーザーに確認してください
• シェルのエスケープ： ! を含む Sheets の範囲は、bash の履歴展開を防ぐためシングルクォートで囲んでください
• 大きなペイロード： JSON を一時ファイルに書き込み、インラインではなく $(cat /tmp/file.json) を使用してください