google-workspace-cli

Google Workspace CLI

オープンソースの gws CLI（github.com/googleworkspace/cli、Apache-2.0）を使った、Google Workspace 管理の専門的なガイダンスと自動化です。CLI は Google の Discovery Service から動的にコマンドを生成するため、サポートされているすべての Workspace API と、+ 接頭辞付きのヘルパーコマンドを利用できます。このスキルでは、ローカルの Python ツール（doctor、認証ガイド、レシピカタログ、セキュリティ監査、出力アナライザー）を追加します。

スクリプトを作成する前に確認してください： gws は Google の API Discovery ドキュメントから実行時にコマンドを生成し、CLI は v1.0 前の段階です。自動化に組み込む前に、必ず gws --help、gws <service> --help、または gws schema <service>.<resource>.<method> でコマンドの正確な仕様を確認してください。このスキル内で (verify) と記されたコマンドは、gws <service> <resource> <method> パターンの例であり、インストール済みのバージョンで確認する必要があります。

---

クイックスタート

インストールを確認する

# Verify gws is installed and authenticated
python3 scripts/gws_doctor.py

メールを送信する

gws gmail +send --to "[email protected]" \
  --subject "Weekly Update" --body "Here's this week's summary..."

Drive のファイルを一覧表示する

gws drive files list --params '{"pageSize": 20}' | python3 scripts/output_analyzer.py --select "name,mimeType,modifiedTime" --format table

---

インストール

npm（推奨。Node.js 18+ が必要です）

npm install -g @googleworkspace/cli
gws --version

Homebrew（macOS/Linux）

brew install googleworkspace-cli

Cargo（ソースから）

cargo install --git https://github.com/googleworkspace/cli --locked
gws --version

ビルド済みバイナリ

macOS、Linux、または Windows 用のバイナリは、github.com/googleworkspace/cli/releases からダウンロードしてください。Nix ユーザーは nix run github:googleworkspace/cli を使用できます。

インストールを検証する

python3 scripts/gws_doctor.py
# Checks: PATH, version, auth status, service connectivity

---

認証

OAuth のセットアップ（対話形式）

# Step 1: Create Google Cloud project and OAuth credentials
python3 scripts/auth_setup_guide.py --guide oauth

# Step 2: Run interactive auth setup (uses gcloud if available)
gws auth setup

# Step 3: Log in, requesting only the scopes you need
gws auth login -s drive,gmail,sheets

ヘッドレス環境／CI

# Generate setup instructions
python3 scripts/auth_setup_guide.py --guide service-account

# Export credentials from an interactive machine, then point the CLI at them
gws auth export --unmasked > credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

環境変数

# Generate .env template
python3 scripts/auth_setup_guide.py --generate-env

変数	用途
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth クライアント ID
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth クライアントシークレット
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	エクスポートした認証情報 JSON のパス
GOOGLE_WORKSPACE_CLI_TOKEN	事前に取得した OAuth トークン
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	デフォルトの設定場所を上書きします
GOOGLE_WORKSPACE_CLI_LOG	デバッグログを有効にします

認証を検証する

python3 scripts/auth_setup_guide.py --validate --json
# Tests each service endpoint

---

ワークフロー 1：Gmail の自動化

目標： メールの送信、検索、ラベル付け、フィルタ管理などの操作を自動化します。

送信、返信、転送（ヘルパーコマンド）

# Send a new email
gws gmail +send --to "[email protected]" \
  --subject "Proposal" --body "Please find attached..."

# Reply to a message (auto-threading); check exact flags with: gws gmail +reply --help
gws gmail +reply ...

# Forward a message; check exact flags with: gws gmail +forward --help
gws gmail +forward ...

# Unread inbox summary
gws gmail +triage

検索と確認（Discovery コマンド）

Discovery コマンドは gws <service> <resource> <method> に従い、--params（クエリ／パスパラメーター）と --json（リクエストボディ）を使ってリクエストパラメーターを JSON で指定します。 各メソッドの正確なスキーマを事前に確認してください。

# What does messages.list accept? (verify)
gws schema gmail.users.messages.list

# Search emails (verify against the schema above)
gws gmail users messages list --params '{"userId": "me", "q": "from:[email protected] after:2025/01/01"}' \
  | python3 scripts/output_analyzer.py --count

# List labels (verify)
gws gmail users labels list --params '{"userId": "me"}'

一括操作

まず --dry-run を使用し、ページネーションには --page-all を使用します（各ページにつき JSON 行を 1 つ出力します）。

# Preview, then archive read emails older than 30 days (verify method schema first)
gws gmail users messages list --params '{"userId": "me", "q": "is:read older_than:30d"}' --page-all \
  | python3 scripts/output_analyzer.py --select "id" --format json
# Then feed ids to gmail users messages modify (see: gws schema gmail.users.messages.modify)

---

ワークフロー 2：Drive と Sheets

目標： ファイルの管理、スプレッドシートの作成、共有設定、データのエクスポートを行います。

ファイル操作

# List files
gws drive files list --params '{"pageSize": 50}' \
  | python3 scripts/output_analyzer.py --select "name,mimeType,size" --format table

# Upload a file (helper)
gws drive +upload ./report.pdf --name "Q1 Report"

# Create a Google Sheet
gws sheets spreadsheets create --json '{"properties": {"title": "Budget 2026"}}'

# Download/export — inspect the method first (verify)
gws schema drive.files.export

共有（最初にスキーマを確認してください）

# Inspect the permissions API surface
gws schema drive.permissions.create

# Share with user (verify against schema)
gws drive permissions create --params '{"fileId": "<FILE_ID>"}' \
  --json '{"type": "user", "role": "writer", "emailAddress": "[email protected]"}'

# List who has access (verify)
gws drive permissions list --params '{"fileId": "<FILE_ID>"}'

Sheets のデータ

# Read values (helper); check exact flags with: gws sheets +read --help
gws sheets +read ...

# Append a row (helper); check exact flags with: gws sheets +append --help
gws sheets +append ...

# Or use discovery methods (verify):
gws schema sheets.spreadsheets.values.update
gws sheets spreadsheets values get --params '{"spreadsheetId": "<SHEET_ID>", "range": "Sheet1!A1:D10"}'

---

ワークフロー 3：Calendar と会議

目標： イベントのスケジュール、空き時間の検索、スタンドアップレポートの生成を行います。

イベント管理

# Create an event (helper); check exact flags with: gws calendar +insert --help
gws calendar +insert ...

# Upcoming events (helper, timezone-aware)
gws calendar +agenda

# Or via discovery (verify):
gws schema calendar.events.insert
gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'

空き時間を検索する

# Free/busy via the Calendar API (verify schema first)
gws schema calendar.freebusy.query
gws calendar freebusy query --json '{"timeMin": "...", "timeMax": "...", "items": [{"id": "[email protected]"}]}'

スタンドアップレポート（ワークフローヘルパー）

# Today's meetings + tasks
gws workflow +standup-report \
  | python3 scripts/output_analyzer.py --format table

# Next meeting prep; check exact flags with: gws workflow +meeting-prep --help
gws workflow +meeting-prep

---

ワークフロー 4：セキュリティ監査

目標： Google Workspace のセキュリティ設定を監査し、修正用コマンドを生成します。

完全監査を実行する

# Full audit across all services
python3 scripts/workspace_audit.py --json

# Audit specific services
python3 scripts/workspace_audit.py --services gmail,drive,calendar

# Demo mode (no gws required)
python3 scripts/workspace_audit.py --demo

監査項目

領域	確認項目	リスク
Drive	外部共有が有効	データ流出
Gmail	自動転送ルール	データ流出
Gmail	DMARC/SPF/DKIM レコード	メールのなりすまし
Calendar	デフォルトの共有範囲	情報漏えい
OAuth	サードパーティアプリへの許可	不正アクセス
Admin	スーパー管理者の人数	権限の昇格
Admin	2 段階認証の強制	アカウント乗っ取り

確認と修正

# Review findings
python3 scripts/workspace_audit.py --json | python3 scripts/output_analyzer.py \
  --filter "status=FAIL" --select "area,check,remediation"

# Execute remediation (example: check current Drive settings first; verify)
gws drive about get --params '{"fields": "*"}'
# Follow remediation commands from audit output (verify each against gws --help)

---

Python ツール

スクリプト	目的	使用方法
gws_doctor.py	事前診断	python3 scripts/gws_doctor.py [--json] [--services gmail,drive]
auth_setup_guide.py	認証設定ガイド	python3 scripts/auth_setup_guide.py --guide oauth
gws_recipe_runner.py	レシピカタログと実行ツール	python3 scripts/gws_recipe_runner.py --list [--persona pm]
workspace_audit.py	セキュリティ／設定の監査	python3 scripts/workspace_audit.py [--json] [--demo]
output_analyzer.py	JSON／NDJSON の分析	gws ... --json | python3 scripts/output_analyzer.py --count

すべてのスクリプトは標準ライブラリのみを使用し、--json 出力をサポートしています。また、埋め込みのサンプルデータを使ったデモモードも備えています。

---

ベストプラクティス

セキュリティ

1. 最小限のスコープで OAuth を使用し、各ワークフローに必要なものだけをリクエストします
2. トークンはシステムのキーリングに保存し、プレーンテキストファイルには決して保存しません
3. サービスアカウントキーは 90 日ごとにローテーションします
4. サードパーティの OAuth アプリへの許可を四半期ごとに監査します
5. 破壊的な一括操作の前に --dry-run を使用します

自動化

1. すべての gws 出力は構造化 JSON です。フィルタリングや集計には output_analyzer.py にパイプで渡します
2. 複数ステップの操作では、生のコマンドを連結する代わりに gws workflow +* ヘルパーを使用します
3. ローカルのレシピカタログ（gws_recipe_runner.py）をコマンドテンプレートとして使用し、それぞれを gws --help で確認します
4. --page-all はページごとに 1 行の JSON（NDJSON）を出力し、大きな結果セットをストリーミングできます
5. 実行前にリクエストをプレビューするには --dry-run を使用します

パフォーマンス

1. --params の API の fields パラメーターで必要なフィールドだけをリクエストします（ペイロードサイズを削減できます）
2. 結果を参照する際は --params の pageSize を使用して件数を制限します
3. 完全なデータセットが必要な場合にのみ --page-all を使用し、--page-limit／--page-delay で調整します
4. 手作業で連結した API 呼び出しよりも、+ ヘルパー（最適化された単一の呼び出し）を優先します
5. 頻繁にアクセスするデータ（ラベル ID、フォルダー ID など）は変数にキャッシュします

---

制限事項

制約	影響
OAuth トークンの有効期限は 1 時間です	長時間実行するスクリプトでは再認証が必要です
API のレート制限（ユーザーごと、サービスごと）	一括操作で 429 エラーが発生する場合があります
必要なスコープはサービスによって異なります	認証時に正しいスコープをリクエストする必要があります
v1.0 前の CLI ステータス	リリース間で互換性を損なう変更が発生する可能性があります
Google Cloud プロジェクトが必要です	無料ですが、Cloud Console での設定が必要です
Admin API には管理者権限が必要です	一部の監査チェックには Workspace Admin ロールが必要です

サービスごとの必須スコープ

# List scopes for specific services
python3 scripts/auth_setup_guide.py --scopes gmail,drive,calendar,sheets

サービス	主なスコープ
Gmail	gmail.modify, gmail.send, gmail.labels
Drive	drive.file, drive.metadata.readonly
Sheets	spreadsheets
Calendar	calendar, calendar.events
Admin	admin.directory.user.readonly, admin.directory.group
Tasks	tasks