Google Workspace CLI (gws)

Rust で構築された CLI ツールで、すべての Google Workspace API をコンポーザブルなコマンドでラップし、構造化された JSON 出力を生成します。Google の Discovery Service から動的にコマンド構造を構築するため、更新なしで常に最新の API をサポートします。

前提条件

• gcloud CLI: 認証に必須です。macOS では brew install --cask google-cloud-sdk でインストールしてください。
• Node.js/npm: gws のインストールに必須です。

インストール＆セットアップ

# 1. CLI をインストール
npm install -g @googleworkspace/cli

# 2. 認証をセットアップ(GCP プロジェクト + OAuth のインタラクティブな手順)
gws auth setup

# 3. Google Workspace アカウントにログイン
gws auth login

gws auth setup コマンドは以下を実行します：

1. GCP プロジェクトの作成または選択（すべて CLI 経由）
2. 必要な Google Workspace API の有効化
3. OAuth クライアント構成

複数のアカウント(仕事、個人)を追加できます。エージェント専用アカウントの場合は、完全アクセス(すべての OAuth スコープ)を付与します。個人/仕事用アカウントの場合は、限定アクセスから開始してください。

コア使用パターン

コマンド構造

# 標準 API 呼び出し
gws <service> <resource> <method> --params '{"key": "value"}' --json '{"body": "data"}'

# ヘルパーショートカット(エンコード/フォーマットを処理)
gws <service> +<helper> --flag value

主要なサービス＆ヘルパー

サービス	一般的なヘルパー	目的
gmail	+send、+triage	メール管理
calendar	+agenda、+insert	スケジュール管理
drive	+upload	ファイル管理
sheets	+read、+append	スプレッドシート操作
docs	+write	ドキュメント操作
chat	+send	チームメッセージング

すべてのレスポンスは、エージェント解析に信頼性の高い構造化 JSON を返します。

Gmail

# 受信トレイを検索
gws gmail users messages list --params '{"userId": "me", "q": "is:unread"}'

# メッセージを読む
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}'

# メール送信(ヘルパーが RFC 2822 エンコーディングを処理)
gws gmail +send --to alice@company.com --subject 'Report Ready' \
  --body 'The Q2 report is ready for review.'

# 未読をトリアージ
gws gmail +triage --max 5 --query 'from:boss'

Calendar

# 今日のアジェンダ
gws calendar +agenda

# イベント作成
gws calendar +insert --summary 'Standup' \
  --start '2026-03-10T09:00:00-07:00' \
  --end '2026-03-10T09:30:00-07:00'

# 参加者付き定期イベント作成
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Weekly Standup",
    "start": {"dateTime": "2026-03-10T09:00:00", "timeZone": "America/Vancouver"},
    "end": {"dateTime": "2026-03-10T09:30:00", "timeZone": "America/Vancouver"},
    "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
    "attendees": [{"email": "team@company.com"}]
  }'

Drive

# 最近のファイルをリスト
gws drive files list --params '{"pageSize": 10}'

# ファイルをアップロード
gws drive +upload --file ./report.pdf --parent FOLDER_ID

# フォルダを作成
gws drive files create --json '{"name": "Q2 Project", "mimeType": "application/vnd.google-apps.folder"}'

# ダウンロード / エクスポート
gws drive files get --params '{"fileId": "FILE_ID", "alt": "media"}' -o report.pdf
gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}' -o doc.pdf

# 他のユーザーと共有
gws drive permissions create --params '{"fileId": "FOLDER_ID"}' \
  --json '{"role": "writer", "type": "user", "emailAddress": "colleague@company.com"}'

Sheets

# 範囲を読む
gws sheets +read --spreadsheet-id SHEET_ID --range 'Contacts!A2:C'

# 行を追加
gws sheets +append --spreadsheet-id SHEET_ID --range 'Sheet1' \
  --values '["2026-03-05", "Marketing", "Ad spend", "1500"]'

Docs、Chat、Meet、Forms

# ドキュメント作成
gws docs documents create --json '{"title": "Meeting Notes"}'

# ドキュメントに書き込む
gws docs +write --document-id DOC_ID \
  --text '## Project: Q2 Launch\n\n### Objective\nLaunch by end of Q2.'

# チャットメッセージを送信
gws chat +send --space spaces/TEAM_SPACE --text 'Check updated policy.'

# Meet ルームを作成
gws meet spaces create --json '{"config": {"accessType": "OPEN"}}'

# フォームを作成
gws forms forms create --json '{"info": {"title": "Feedback", "documentTitle": "Feedback Form"}}'

MCP サーバー統合

Claude Code とのより深い統合のために、gws は組み込み MCP サーバーを提供します：

# 特定のサービスで MCP サーバーを起動
gws mcp -s drive,gmail,calendar

.mcp.json または Claude Desktop 設定で構成します：

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

各サービスは約 10～80 のツールを追加します。ツール制限を超えないよう、サービスリストは焦点を絞ってください。

リポジトリからのエージェントスキル

gws リポジトリには 100 以上の SKILL.md ファイル(サービススキル、ペルソナバンドル、ヘルパー、レシピ)が付属しています。references/services.md で完全なカタログとペルソナの詳細を参照してください。

# すべてのスキルをクローンしてシンボリックリンク
git clone https://github.com/googleworkspace/cli.git
ln -s $(pwd)/cli/skills/gws-* ~/.claude/skills/

# または特定のものをコピー
cp -r cli/skills/gws-drive cli/skills/gws-gmail ~/.claude/skills/

モデルアーマー(安全性)

API レスポンスをサニタイズして、メール/ドキュメント コンテンツからのプロンプトインジェクションを防ぎます：

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

モード: warn(疑わしいコンテンツにフラグを立てる)または block(削除)。

追加リソース

リファレンスファイル

• references/services.md - すべてのヘルパーと API パターンを含む完全なサービスリスト
• references/setup-troubleshooting.md - 一般的なセットアップの問題と OAuth 構成の詳細

スクリプト

• scripts/check-gws.sh - gws インストールと認証ステータスを確認