Google Workspace CLI（gws）使い方 2026 — GitHub公開直後に試した全コマンド
Hacker Newsで427ポイントを記録したGoogle公式CLI「gws」の日本語完全ガイド。npmでインストールしてGmail・Drive・Calendar・Sheetsをコマンド1行で操作する方法、OAuth認証設定、サービス別全コマンド例、AIエージェント連携・セキュリティ対策まで網羅。
Google Workspace CLI（gws）は、Drive・Gmail・Calendar・Sheets・Docs・Chat・Adminなど、Google Workspaceの全サービスをターミナルから操作できるCLIツールです。
2026年3月2日にGitHubで公開され、Hacker Newsで427ポイントを記録。GitHubスターは急速に伸び続けており、Workspace系CLIとしては異例のペースで成長中です。
この記事では、gwsのインストールから認証設定、サービスごとの全コマンド例、AIエージェント連携、セキュリティ対策、既存ツールとの比較まで、日本語で網羅的にまとめます。
gwsの概要
gws（Google Workspace CLI）はRust製のコマンドラインツールで、npmパッケージとして配布されています。
最大の特徴は動的コマンド構築です。GoogleのDiscovery Serviceを実行時に読み込んで、コマンド体系を自動生成します。Google側でAPIエンドポイントが追加されると、gwsを更新しなくても新しいコマンドが使えるようになります。
主な機能は以下の通りです。
- Google Workspace全サービスのAPI操作（Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin等）
- 構造化JSON出力（
jqやスクリプトとの連携に最適） --dry-runによるリクエストプレビュー- 自動ページネーション・マルチパートアップロード
- AES-256-GCMによる認証情報の暗号化保存
- MCP（Model Context Protocol）サーバー内蔵
- 100以上のAIエージェント向けスキル
- Model Armorによるプロンプトインジェクション対策
注意: gwsはGoogleの公式サポート対象外の製品です。READMEに明記されています。2026年3月13日時点の最新バージョンはv0.13.2で、v1.0に向けて破壊的変更が予定されています。公開から10日でv0.3→v0.13まで進んでおり、開発ペースはかなり速いです。
内部アーキテクチャ
gwsは2段階のパーシング戦略を採用しています。argv[1]からサービス名を識別し、該当サービスのDiscovery Documentをフェッチ（24時間キャッシュ）。そこからclap::Commandツリーを動的に構築して、残り引数を再パースし、認証・HTTPリクエスト構築・実行を行います。
全出力（成功レスポンス、エラー、メタデータ）は構造化JSONです。
インストールと認証設定
インストール
npm（推奨）:
npm install -g @googleworkspace/clinpmパッケージにプリビルドネイティブバイナリが含まれているため、Rustのツールチェインは不要です。
ソースからビルド:
git clone https://github.com/googleworkspace/cli.git
cd cli
cargo install --path .Nix:
nix run github:googleworkspace/cli各OS向けのプリビルドバイナリはGitHub Releasesからもダウンロードできます。インストール後はgws --versionで動作確認してください。
認証方法
gwsを使うにはOAuth認証が必要です。用途に応じて5つの方法があります。
方法1: インタラクティブセットアップ（個人利用向け・推奨）
最もシンプルな方法です。GCPプロジェクトの作成からOAuth設定までを対話形式で進めます。前提としてgcloud CLI（Google Cloud SDK）が必要です。
gws auth setup # 初回のワンタイムセットアップ
gws auth login # ログイン（以後はこれだけでOK）方法2: Google Cloud Consoleで手動設定
gcloudを使わない場合や、既存のGCPプロジェクトを使いたい場合はこちらです。
- Google Cloud Consoleでプロジェクトを作成
- 「APIとサービス」→「OAuth同意画面」→ アプリタイプ「External」を選択
- 「テストユーザー」に自分のメールアドレスを追加（これを忘れると403エラーになる）
- 「認証情報」→「OAuth 2.0クライアントID」→「デスクトップアプリ」で作成
- JSONをダウンロードして
~/.config/gws/client_secret.jsonに配置 gws auth loginを実行
「このアプリはGoogleで確認されていません」の警告が出ますが、テスト利用なら「詳細」→「（アプリ名）に移動」で進めて問題ありません。
方法3: サービスアカウント（CI/CD向け）
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com # DWD時のみ
gws drive files list方法4: 事前取得アクセストークン
export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
gws drive files list方法5: ヘッドレス/CI環境
# インタラクティブマシンでエクスポート
gws auth export --unmasked > credentials.json
# ヘッドレスマシンで使用
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list認証の優先度
gwsは以下の順序で認証情報を探します。
- 環境変数
GOOGLE_WORKSPACE_CLI_TOKEN（アクセストークン直指定） - 環境変数
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE（認証情報ファイル） gws auth loginで保存された暗号化認証情報~/.config/gws/credentials.json（プレーンテキスト）
複数アカウント管理
gws auth login --account work@example.com
gws auth login --account personal@gmail.com
gws auth list # 登録済みアカウント一覧
gws auth default work@example.com # デフォルト切り替え
gws --account personal@gmail.com drive files list # 一時的に別アカウント使用スコープ設定の注意点
gwsのrecommendedプリセットは85以上のOAuthスコープを含みますが、テストモード（未検証アプリ）では約25スコープまでしか許可されません。必要なサービスだけに絞って認証するのが確実です。
gws auth login --scopes drive,gmail,calendarコマンドリファレンス
共通オプション・ページネーション
# リクエストをプレビュー（実行しない）
gws <service> <resource> <method> --dry-run
# APIスキーマを確認
gws schema <service>.<resource>.<method>
# ヘルプ表示（全リソースで使用可能）
gws <service> <resource> <method> --help
# 別アカウントで一時実行
gws --account user@example.com <command>
# 全ページを自動取得（NDJSON形式で出力）
gws drive files list --page-all
# 最大ページ数を制限 / ページ間遅延
gws drive files list --page-all --page-limit 5 --page-delay 200Google Drive
# ファイル一覧を取得（最新5件）
gws drive files list --params '{"pageSize": 5}'
# 更新日時の降順で取得
gws drive files list --params '{"pageSize": 10, "orderBy": "modifiedTime desc"}'
# 名前でファイル検索
gws drive files list --params '{"q": "name contains '\''レポート'\''", "pageSize": 10}'
# MIMEタイプでフィルタ（スプレッドシートのみ）
gws drive files list --params '{"q": "mimeType = '\''application/vnd.google-apps.spreadsheet'\''", "pageSize": 10}'
# ファイルをアップロード
gws drive files create \
--json '{"name": "report.pdf", "parents": ["FOLDER_ID"]}' \
--upload ./report.pdf
# ファイルのメタデータを取得
gws drive files get --params '{"fileId": "FILE_ID", "fields": "id,name,mimeType,modifiedTime,size"}'
# 全ファイルをページング取得
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'Gmail
# 未読メール一覧を取得
gws gmail users messages list \
--params '{"userId": "me", "q": "is:unread", "maxResults": 10}'
# 特定のラベルのメールを取得
gws gmail users messages list \
--params '{"userId": "me", "q": "label:important", "maxResults": 5}'
# 期間指定でメール検索
gws gmail users messages list \
--params '{"userId": "me", "q": "after:2026/03/01 before:2026/03/07", "maxResults": 20}'
# メールの詳細を取得
gws gmail users messages get \
--params '{"userId": "me", "id": "MESSAGE_ID"}'
# ラベル一覧を取得
gws gmail users labels list --params '{"userId": "me"}'Google Calendar
# 今日の予定を取得
gws calendar events list \
--params '{"calendarId": "primary", "timeMin": "2026-03-06T00:00:00Z", "timeMax": "2026-03-06T23:59:59Z", "singleEvents": true, "orderBy": "startTime"}'
# 今週の予定を取得
gws calendar events list \
--params '{"calendarId": "primary", "timeMin": "2026-03-03T00:00:00Z", "timeMax": "2026-03-09T23:59:59Z", "singleEvents": true, "orderBy": "startTime"}'
# カレンダー一覧を取得
gws calendar calendarList list
# 予定を作成
gws calendar events insert \
--params '{"calendarId": "primary"}' \
--json '{"summary": "チームMTG", "start": {"dateTime": "2026-03-07T10:00:00+09:00"}, "end": {"dateTime": "2026-03-07T11:00:00+09:00"}}'Google Sheets
Sheetsの範囲指定には!が含まれるため、--paramsの値は必ずシングルクォートでラップしてください。
# セル範囲を読み取り
gws sheets spreadsheets values get \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:C10"}'
# 行を追加（既存データの末尾に）
gws sheets spreadsheets values append \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
--json '{"values": [["Name", "Score", "Date"], ["Alice", 95, "2026-03-06"]]}'
# セル範囲を上書き
gws sheets spreadsheets values update \
--params '{"spreadsheetId": "SHEET_ID", "range": "Sheet1!A1:B2", "valueInputOption": "USER_ENTERED"}' \
--json '{"values": [["Updated", "Data"], ["Row2", "Col2"]]}'
# スプレッドシートを新規作成
gws sheets spreadsheets create \
--json '{"properties": {"title": "Monthly Report"}}'Google Chat・Docs・Admin
# Chat: メッセージを送信
gws chat spaces messages create \
--params '{"parent": "spaces/SPACE_ID"}' \
--json '{"text": "デプロイが完了しました。"}'
# Docs: ドキュメントを新規作成
gws docs documents create \
--json '{"title": "議事録 2026-03-06"}'
# Admin: ユーザー一覧を取得
gws admin users list \
--params '{"domain": "example.com", "maxResults": 50}'
# Admin: グループ一覧を取得
gws admin groups list \
--params '{"domain": "example.com"}'スコープ完全リファレンス — 権限を正確に絞る方法
gwsの--scopesオプション、ドキュメントを読んでも「エイリアスが何を指しているか」が分かりにくい。フルURLとエイリアスが混在していて、試行錯誤で30分溶かした経験があるので整理しておく。
よく使うエイリアスとフルURL対応表
| エイリアス | OAuthスコープURL | 権限範囲 |
|---|---|---|
drive | https://www.googleapis.com/auth/drive | Drive全操作（読み書き削除） |
drive.readonly | https://www.googleapis.com/auth/drive.readonly | 読み取り・ダウンロードのみ |
drive.file | https://www.googleapis.com/auth/drive.file | gwsが作成したファイルのみ操作可 |
gmail | https://mail.google.com/ | Gmail全操作（送受信・削除含む） |
gmail.readonly | https://www.googleapis.com/auth/gmail.readonly | 読み取りのみ |
calendar | https://www.googleapis.com/auth/calendar | カレンダー全操作 |
calendar.readonly | https://www.googleapis.com/auth/calendar.readonly | 読み取りのみ |
sheets | https://www.googleapis.com/auth/spreadsheets | Sheets全操作 |
sheets.readonly | https://www.googleapis.com/auth/spreadsheets.readonly | 読み取りのみ |
chat | https://www.googleapis.com/auth/chat.messages | ChatメッセージCRUD |
admin | https://www.googleapis.com/auth/admin.directory.user | Adminユーザー管理 |
recommended | 85以上のスコープを一括付与 | 全サービスの全操作（非推奨） |
テストモード（25スコープ上限）の突破法
OAuthアプリが未審査のテストモード状態だと、Googleが許可するスコープは約25個まで。--scopes recommended は85以上をリクエストするので即エラーになる。
突破法は2つ。
.readonly エイリアスを使う。書き込みが不要ならreadonly系に差し替えるだけでスコープ消費を大幅に節約できる。
# 書き込みなしなら .readonly を優先
gws auth login --scopes drive.readonly,gmail.readonly,calendar.readonlyフルURLで直接指定する方法もある。エイリアスが認識されない環境や、スコープを細かく制御したい場合に有効。
gws auth login --scopes "https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/calendar"スコープを変更したあとはいったんログアウトして再認証が必要。
gws auth logout
gws auth login --scopes drive,calendarjq × gws — ターミナル1行で業務データを加工する
gwsの出力はすべて構造化JSONなので、jq と組み合わせると実用性が一段上がる。「取得 → 加工 → 別コマンドに渡す」をシェル1行で閉じられるのが強みで、よく使うパターンを整理しておく。
Drive全ファイルをCSVで書き出す
gws drive files list \
--params '{"pageSize": 100}' --page-all \
| jq -r '.files[] | [.id, .name, .mimeType, .modifiedTime] | @csv' \
> drive_files.csv未読メール件数をカウント
gws gmail users messages list \
--params '{"userId": "me", "q": "is:unread"}' \
| jq '.resultSizeEstimate'今週の予定をMarkdown形式で出力（macOS向け）
gws calendar events list \
--params "{
\"calendarId\": \"primary\",
\"timeMin\": \"$(date -u +%Y-%m-%dT00:00:00Z)\",
\"timeMax\": \"$(date -u -v+7d +%Y-%m-%dT23:59:59Z)\",
\"singleEvents\": true,
\"orderBy\": \"startTime\"
}" \
| jq -r '.items[] | "- \(.start.dateTime // .start.date | .[0:10]) \(.summary)"'特定ワードを含むファイルのURLを一覧表示
# "レポート"を含むファイルのwebViewLinkをタブ区切りで出力
gws drive files list \
--params '{"q": "name contains '\''レポート'\''", "fields": "files(name,webViewLink)", "pageSize": 50}' \
| jq -r '.files[] | "\(.name)\t\(.webViewLink)"'最新更新ファイルTOP5を名前でリスト
gws drive files list \
--params '{"orderBy": "modifiedTime desc", "pageSize": 5, "fields": "files(name,modifiedTime)"}' \
| jq -r '.files[] | "\(.modifiedTime | .[0:10]): \(.name)"'jqで出力を絞ってから別コマンドに渡せば、Drive → Chat の通知パイプラインも1スクリプトで完結する。
AIエージェント連携
gwsの設計上の大きな特徴は、AIエージェントとの連携が最初から組み込まれている点です。
MCPサーバー
MCP（Model Context Protocol）サーバーが内蔵されており、Claude Desktop、Gemini CLI、VS Codeなど、MCP対応クライアントからWorkspace APIを直接呼び出せます。
gws mcp -s drive # 特定サービスのみ公開
gws mcp -s drive,gmail,calendar # 複数サービス
gws mcp -s all # 全サービス
gws mcp -s drive,gmail -w # ワークフローツールも含めるMCP削除→復活の経緯
このMCPサーバーは、実は一度完全に削除されている。v0.8.0（2026年3月6日）でMCPの全コード1,151行が削除された（PR #275）。理由は設計上の衝突だった。MCPプロトコルは「利用可能なツール定義を全てクライアントに事前送信する」モデルだが、gwsはDiscovery Serviceから動的にAPIコマンドを生成する設計で、全サービスを公開すると200〜400個のツール定義になり、コンテキストウィンドウを40,000〜100,000トークン消費してしまう。さらにMCPのツール命名規約（スネークケース）とGoogleのドット区切り命名（calendar.events.list）の非互換も重なった。ただコミュニティの反発が大きく、Claude Desktop・Gemini CLI・VS Code・Cursorの4クライアントからの需要もあり、v0.9.xで再編成されて復活した。この経緯を知っておくと、下記の--tool-modeがなぜ重要なのかが理解しやすい。
—tool-mode: compactとfullの使い分け
| モード | ツール数の目安 | 挙動 | 向いているケース |
|---|---|---|---|
| full（デフォルト） | 3サービスで60〜80 | 各APIメソッドが個別ツールとして公開 | 使うサービスが3つ以下、レスポンス速度優先 |
| compact | 約26個に圧縮 | 1サービス1ツール＋gws_discoverメタツールで2段階呼び出し | 4サービス以上を同時公開、コンテキスト節約優先 |
gws mcp -s drive,gmail,calendar --tool-mode compactClaude Code（コンテキスト200K）はfullで十分だが、コンテキストの小さいクライアントや多サービス公開時はcompactが有利。
Claude Desktop × gws MCP 実践ワークフロー
MCPサーバーを有効にすると、Claude Desktopから自然言語でGoogle Workspaceを操作できます。
Claude Desktopの設定（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）:
{
"mcpServers": {
"gws": {
"command": "gws",
"args": ["mcp", "-s", "drive,gmail,calendar"]
}
}
}設定後、Claudeのチャットで以下のような指示が通ります。
- 「今日の予定を確認して、15時以降で空いてる1時間のスロットを教えて」
- 「先週届いたメールの中から、見積書が添付されてるものを探して」
- 「Driveの『2026年Q1レポート』フォルダにあるスプレッドシートの一覧を出して」
- 「明日の10時から11時で『デザインレビュー』という予定をカレンダーに入れて」
Claudeは内部的にgwsのMCPツールを呼び出して、Calendar APIのevents.list → 空きスロット計算 → events.insert のように複数のAPI呼び出しを自動で組み合わせます。こうした多ステップの自律実行には、エージェント性能の高いモデルが適している。Claude Sonnet 5はTerminal-BenchでSonnet 4.6比+13ptと大幅向上しており、gws × MCPの組み合わせでも精度が上がる。
MCPツール数の上限に注意。 -s all で全サービスを公開すると、サービスあたり10〜80個のツールが登録され、合計で数百ツールになります。MCPクライアントの多くはツール数50〜100が実用的な上限で、それを超えるとレスポンスが遅くなったり、ツール選択の精度が落ちます。普段使いなら -s drive,gmail,calendar 程度に絞るのが現実的です。
Gemini CLIとの連携
Gemini CLIからも同様にgwsを利用できます。
# Gemini CLIにgwsをエクステンションとしてインストール
gemini extensions install https://github.com/googleworkspace/cli
# 自然言語でWorkspace操作
gemini "今週のカレンダーの予定を一覧にして、空き時間を30分単位で出して"Gemini CLIはGoogleのエコシステムとの親和性が高く、Geminiモデルがgwsのツール呼び出しを処理します。Google Workspace管理者がGemini CLIで管理タスクを自然言語実行するユースケースが想定されています。
Agent Skills
100以上のプリビルドスキルが同梱されており、4カテゴリに分類されています。
- Services（26種）: 各APIのコアスキル（Drive, Gmail, Calendar等）
- Helpers（20種）: 頻出操作のショートカット
- Personas（10種）: 役職別スキルバンドル（エグゼクティブアシスタント、PM等）
- Recipes（47種）: 複数ステップの自動化シーケンス
# 全スキルを一括追加
npx skills add https://github.com/googleworkspace/cli
# 個別サービスのスキルを追加
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
# OpenClawでのセットアップ
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/Model Armor（プロンプトインジェクション対策）
AIエージェントがメールやドキュメントを読む際、悪意のあるプロンプトインジェクションが混入するリスクがあります。gwsにはGoogle Cloud Model Armorとの統合が組み込まれています。Model Armorはフルマネージドのセキュリティサービスで、Gemini・OpenAI・Anthropicなど特定のLLMに依存せず使えます。
検出できる脅威は5カテゴリ。
| フィルタ | 検出対象 |
|---|---|
| プロンプトインジェクション/ジェイルブレイク | LLMの指示を無視させる操作、安全フィルタの回避 |
| 責任あるAI（RAI） | ヘイトスピーチ、ハラスメント、露骨なコンテンツ |
| 悪意あるURL | フィッシング、マルウェア配布サイトへのリンク |
| 機密データ（SDP） | クレジットカード番号、SSN、APIキー |
| CSAM | 児童の安全に関するコンテンツ（常時有効） |
# 個別リクエストでサニタイズ
gws gmail users messages get --params '...' \
--sanitize "projects/PROJECT/locations/LOCATION/templates/TEMPLATE"
# 環境変数でデフォルト設定
export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/P/locations/L/templates/T"
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="block" # warnまたはblockwarn（デフォルト）は検出結果をログするだけでレスポンスはそのまま返す。block は検出時にレスポンスを遮断する。最初はwarnで1〜2週間運用して誤検知の傾向を掴み、問題なければblockに切り替えるのが安全だ。テンプレートはGoogle Cloudコンソール（Security > Model Armor）かgcloudで作成する。信頼度レベルはMEDIUM_AND_ABOVEが推奨の開始点。2026年3月時点でModel Armorはus-central1・us-east4・us-west1・europe-west4のみ対応で、日本リージョン（asia-northeast1）は未対応（us-west1経由が最寄り）。フリーランスが個人メールを処理するだけなら不要だが、外部クライアントのメールをAIエージェントに読ませる場合や顧客データを扱う場合は有効化を検討する価値がある。リクエスト1,000件あたり約$0.60程度（ティア次第）で、日数十件のエージェント処理ならコストはほぼ無視できる。
OAuthセットアップで絶対ハマるポイント
gwsの最大のハードルはOAuth認証の初期設定です。CLIの操作自体はシンプルですが、GCPコンソール側の設定で30〜45分かかることがあります。ここでは、実際にハマりやすいポイントをステップごとに整理します。
セットアップ全体の流れ
GCPプロジェクト作成
→ API有効化（Drive API, Gmail API等を個別にEnable）
→ OAuth同意画面の設定
→ テストユーザー追加
→ OAuthクライアントID作成（デスクトップアプリ）
→ client_secret.json配置
→ gws auth loginステップ1: GCPプロジェクト作成とAPI有効化
Google Cloud Consoleでプロジェクトを作成したら、使いたいサービスのAPIを個別に有効化する必要があります。これを忘れると 403 Forbidden や Access Not Configured が返ります。
# gcloud CLIでAPI有効化する場合
gcloud services enable drive.googleapis.com --project=YOUR_PROJECT_ID
gcloud services enable gmail.googleapis.com --project=YOUR_PROJECT_ID
gcloud services enable calendar-json.googleapis.com --project=YOUR_PROJECT_ID
gcloud services enable sheets.googleapis.com --project=YOUR_PROJECT_ID
gcloud services enable docs.googleapis.com --project=YOUR_PROJECT_IDGCPコンソールのGUIからやる場合は「APIとサービス」→「ライブラリ」から検索して個別にENABLEします。「Google Workspace全体を有効化」のようなボタンは存在しないので、1つずつ有効にする必要があります。
ステップ2: OAuth同意画面の設定とテストユーザー登録
同意画面の設定で最も多いミスがテストユーザーの登録忘れです。
OAuthアプリがテストモード（公開ステータス: テスト）の状態では、テストユーザーとして登録したGoogleアカウントしかアクセスできません。登録せずに gws auth login すると Access blocked: This app's request is invalid と表示されます。
設定手順:
- 「APIとサービス」→「OAuth同意画面」を開く
- User Type は External を選択（Google Workspace組織外のアカウントでも使える）
- アプリ名・サポートメール・デベロッパー連絡先を入力
- スコープは後で
gws auth login --scopesで制御するので、ここでは追加しなくてもOK - 「テストユーザー」画面で自分のGmailアドレスを追加する（これが最重要）
ステップ3: OAuthクライアントIDの作成
「認証情報」→「認証情報を作成」→「OAuth 2.0 クライアント ID」で作成しますが、アプリケーションの種類は必ず「デスクトップアプリ」を選択します。
「ウェブ アプリケーション」を選ぶとリダイレクトURIの不一致でエラーになります。gwsはローカルの一時サーバー（http://localhost）でOAuthコールバックを受けるため、デスクトップアプリタイプが前提です。
作成後にJSONをダウンロードし、以下に配置します。
mkdir -p ~/.config/gws
mv ~/Downloads/client_secret_XXXXXX.json ~/.config/gws/client_secret.jsonステップ4: gws auth loginの実行
# 必要なサービスだけスコープ指定（推奨）
gws auth login --scopes drive,gmail,calendar
# ブラウザが自動で開くのでGoogleアカウントでログイン
# 「このアプリはGoogleで確認されていません」→「詳細」→「(アプリ名)に移動」で進めるよくあるトラブルと原因
| 症状 | 原因 | 対処 |
|---|---|---|
Access blocked | テストユーザー未登録 | OAuth同意画面でメールアドレスを追加 |
redirect_uri_mismatch | クライアントタイプが「ウェブ」になっている | 「デスクトップアプリ」で再作成 |
| スコープ関連エラー | テストモードの25スコープ制限超過 | --scopes drive,gmail で絞る |
API has not been used | GCPプロジェクトでAPI未有効化 | gcloud services enable で有効化 |
gws auth setup が途中で止まる（Windows） | Windows環境での既知の問題 | 手動セットアップ（方法2）を使う |
| ブラウザが開かない | ヘッドレス環境 or WSL | gws auth export で別マシンから認証情報を持ち込む |
補足: gws auth setup vs 手動セットアップ
gws auth setup は gcloud CLI経由でGCPプロジェクト作成からOAuth設定まで自動化してくれますが、内部で何をやっているか分からないまま進むと、エラー時に手詰まりになります。上記の手動ステップを一度は理解しておくと、トラブルシューティングが格段に楽になります。
また、gws auth setup はWindows環境では不安定な報告があり、その場合は手動セットアップ一択です。
シェルスクリプトで組む業務自動化3選
gwsをスクリプトに組み込んでcronに投げると、Workspaceの操作を完全にバックグラウンドで回せる。僕が実際に使っているパターンを3つ。
1. 前日のDrive更新ファイルをChatに朝通知
毎朝9時にcronで動かしているスクリプト。チームのChat Spaceに「昨日変更されたファイル」を流すだけのシンプルな自動化。
#!/bin/bash
# macOS: -v-1d / Linux: -d '-1 day'
YESTERDAY=$(date -u -v-1d +%Y-%m-%dT00:00:00Z 2>/dev/null || date -u -d '-1 day' +%Y-%m-%dT00:00:00Z)
SPACE_ID="spaces/YOUR_SPACE_ID"
FILES=$(gws drive files list \
--params "{\"q\": \"modifiedTime > '${YESTERDAY}'\", \"fields\": \"files(name,webViewLink)\", \"pageSize\": 20}" \
| jq -r '.files[] | "• \(.name)\n \(.webViewLink)"')
[ -n "$FILES" ] && gws chat spaces messages create \
--params "{\"parent\": \"${SPACE_ID}\"}" \
--json "{\"text\": \"*昨日更新されたファイル*\n\n${FILES}\"}"cronに登録:
# crontab -e で追加（平日9時）
0 9 * * 1-5 /path/to/drive_notify.sh2. 今週のカレンダー予定を月曜朝にメール送信
#!/bin/bash
MY_EMAIL="your@gmail.com"
WEEK_START=$(date -u +%Y-%m-%dT00:00:00Z)
WEEK_END=$(date -u -v+7d +%Y-%m-%dT23:59:59Z 2>/dev/null || date -u -d '+7 days' +%Y-%m-%dT23:59:59Z)
EVENTS=$(gws calendar events list \
--params "{
\"calendarId\": \"primary\",
\"timeMin\": \"${WEEK_START}\",
\"timeMax\": \"${WEEK_END}\",
\"singleEvents\": true,
\"orderBy\": \"startTime\"
}" \
| jq -r '.items[] | "\(.start.dateTime // .start.date | .[0:10]): \(.summary)"')
BODY="From: ${MY_EMAIL}\nTo: ${MY_EMAIL}\nSubject: 今週の予定\nContent-Type: text/plain; charset=utf-8\n\n${EVENTS}"
ENCODED=$(printf "%b" "$BODY" | base64 | tr -d '\n')
gws gmail users messages send \
--params '{"userId": "me"}' \
--json "{\"raw\": \"${ENCODED}\"}"3. Sheetsの更新を検知してChatに通知
#!/bin/bash
SHEET_ID="YOUR_SHEET_ID"
CACHE_FILE="/tmp/gws_sheet_cache"
SPACE_ID="spaces/YOUR_SPACE_ID"
# 最新行を取得
LATEST=$(gws sheets spreadsheets values get \
--params "{\"spreadsheetId\": \"${SHEET_ID}\", \"range\": \"Sheet1!A:D\"}" \
| jq -r '.values[-1] | @csv')
LAST=$(cat "$CACHE_FILE" 2>/dev/null || echo "")
if [ "$LATEST" != "$LAST" ] && [ -n "$LATEST" ]; then
gws chat spaces messages create \
--params "{\"parent\": \"${SPACE_ID}\"}" \
--json "{\"text\": \"Sheetsに新規行:\n${LATEST}\"}"
echo "$LATEST" > "$CACHE_FILE"
ficronで1時間ごとに動かせばほぼリアルタイムの監視になる。Zapierを使うと月$29〜かかる操作でも、gwsとシェルスクリプトの組み合わせなら無料。定期実行の自動化をApps Scriptと使い分ける判断軸はこちらに書いた。
Bash直接実行 vs MCP：Claude Codeと組み合わせる時の判断基準
gwsをClaude Codeから使う場合、Bashコマンドとして直接叩く方法と、gws mcpでMCPサーバーを起動して接続する方法の2択がある。
Bash直接実行が向いているケース: 既存スクリプトへの組み込み（cron、LaunchAgent、GitHub Actions）、単発の決まった操作、jqでパイプ加工したい場合、スクリプト化して再現性を保ちたい場合。
MCPモードが向いているケース: 「Driveのプロジェクトフォルダを確認して、対応必要なものをカレンダーに入れて」のような自然言語での横断操作、複数サービスを組み合わせた複合指示、アドホックな判断が必要な作業。
定期実行・スクリプト化したい → Bash直接実行（cron/Routines/GitHub Actions）
複合指示・判断が入る・アドホック → MCPモード（Claude Codeとの対話的セッション）
両方必要 → Routines: Bash直接 / 対話時: MCPモード の使い分けClaude Code Routinesと組み合わせた実務パターンとして、GA4データの週次Sheets転記が分かりやすい。Google Analytics Data APIでデータ取得 → gws sheets appendでSpreadsheetに書き込む2段構成で、コピペ作業がゼロになる。
#!/bin/bash
REPORT=$(curl -s \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}], "metrics": [{"name": "sessions"}], "dimensions": [{"name": "date"}]}' \
"https://analyticsdata.googleapis.com/v1beta/properties/${GA4_PROPERTY_ID}:runReport")
ROWS=$(echo "$REPORT" | jq -r '.rows[] | [.dimensionValues[0].value, .metricValues[0].value] | @csv')
while IFS= read -r row; do
gws sheets spreadsheets values append \
--params "{\"spreadsheetId\": \"${SPREADSHEET_ID}\", \"range\": \"週次GA4!A:B\", \"valueInputOption\": \"USER_ENTERED\"}" \
--json "{\"values\": [[${row}]]}"
done <<< "$ROWS"Claude Code Routinesの週次トリガー（毎週月曜9:00）に設定しておけば、月曜の朝には先週分のデータがSheets上に揃っている。GA4以外でもSearch Console・BigQueryなど、APIがあれば同じパターンでSheets転記を自動化できる。
セキュリティとトラブルシューティング
セキュリティ上の注意点
OAuthスコープは最小限に。 トークン漏洩時の被害範囲を最小化するために、必要なサービスだけに権限を絞ります。
gws auth login --scopes drive,calendar # 推奨
gws auth login --scopes recommended # 非推奨: 全サービスに権限付与認証情報ファイルの管理。 gws auth exportで書き出すファイルにはリフレッシュトークンが含まれます。CI/CD環境ではVault、AWS Secrets Manager等で管理してください。個人〜小規模チームでVaultを立てるほどでもない場合は、1Password（#PR）のCLI連携でも代用できる。client_secret.jsonやエクスポートしたトークンをVaultに入れて op read で都度取得する形にすれば、~/.config/gws/ 以下に平文で置きっぱなしにせずに済む。
公式サポート外のリスク。 gwsはGoogleの公式プロダクトではありません。将来のAPI変更で動作しなくなる可能性があり、本番パイプラインにはフォールバック手段を用意しておくべきです。
OAuthトークンの一般的なリスク。 OAuthトークンはファイアウォールの外に存在し、有効な限りDrive・Gmail・Calendar操作が可能です。定期的なトークンの棚卸しと不要なアクセスの取り消しを行いましょう。
よくあるエラーと対処法
「Access blocked」/ 403エラー → アプリがテストモードで、自分がテストユーザーに登録されていない。OAuth同意画面で追加する。
「Google hasn’t verified this app」 → テストモードでは正常な挙動。「詳細」→「（アプリ名）に移動」で進める。
スコープ関連のエラー → テストモードアプリは約25スコープに制限。--scopes drive,gmail,calendarのように必要なものだけ指定する。
gcloud CLIが見つからない → Google Cloud SDKをインストールするか、手動OAuthセットアップ（本記事「方法2」）を使う。
既存ツールとの比較
Google Workspace関連のCLI・自動化ツールは複数存在します。それぞれ得意領域が異なるため、用途に応じた使い分けが合理的です。
| ツール | 言語 | 対象領域 | MCP対応 | 特徴 |
|---|---|---|---|---|
| gws | Rust | Workspace全サービス | あり | Discovery API動的構築、AIエージェント連携、100+スキル |
| GAM | Python | Workspace管理 | なし | 15年の歴史、ユーザー/グループ/OU管理に特化、エンタープライズ実績 |
| gog | Go | Drive/Gmail/Calendar | なし | 静的コマンド、人間向けのキーストローク最適化、読みやすい出力 |
| gogcli | Go | Gmail/GCal/GDrive | なし | 軽量・シンプル、個人利用向け、steipete/gogcli |
| Google Apps Script | JavaScript | Workspace全サービス | なし | ブラウザ内実行、トリガーによる定期実行、GCP不要 |
| gcloud CLI | Python | GCPインフラ | なし | Workspaceは対象外（IAMやCompute等のGCP管理用） |
GAM（Google Apps Manager） — GitHub約2,500スター。Workspace管理者のデファクトスタンダード。ユーザープロビジョニング、グループ管理、OU設定、ライセンス割り当てなど管理タスクに特化しており、エンタープライズ環境で15年の安定稼働実績があります。GAMADV-XTD3というコミュニティフォークもあり、さらに拡張された機能を提供しています。
gog — Peter Steinberger（OpenClawの開発者）が作ったGo製CLI。gwsがDiscovery APIから動的にコマンドを構築するのに対し、gogは静的にコマンドを定義しています。そのためコマンド補完が効きやすく、人間がターミナルで日常的に使う場合はキーストローク数が少なく、出力も見やすいです。
gogcli（steipete/gogcli） — Go製の軽量CLIで、Gmail・Google Calendar・Google Driveに対応。gwsやgogほど多機能ではないですが、その分セットアップが軽く、個人利用で「メールとカレンダーだけ叩ければいい」というケースに向いています。
Google Apps Script — GCPプロジェクトを用意しなくても、Googleアカウントさえあれば script.google.com でWorkspace全サービスのAPIを叩けます。時間ベースのトリガー（cron的な定期実行）にも対応しており、「毎朝9時にスプレッドシートを更新してメール送信」のようなワークフローを組むならApps Scriptが依然として最も手軽です。ただし、実行時間6分制限・デバッグのしにくさ・ローカル開発環境との連携の弱さがあります。claspを使えばローカルで開発してデプロイできますが、それでもgwsやgogほどのDX（開発者体験）ではありません。
gcloud CLI — GCPインフラの管理ツールで、Compute Engine・Cloud Run・IAMなどが対象です。Google Workspaceのサービス（Drive、Gmail等）は操作対象外ですが、名前が似ているため混同されやすいです。gwsの auth setup は内部で gcloud を使いますが、gcloudそのものはWorkspace操作には使えません。
用途別の選択指針
| やりたいこと | 推奨ツール |
|---|---|
| AIエージェントにWorkspaceを操作させたい | gws |
| MCP経由でLLMからCalendar/Drive/Gmailを叩きたい | gws |
| CI/CDパイプラインでWorkspace操作を自動化したい | gws |
| Workspaceの管理タスク（ユーザー・グループ管理等） | GAM |
| ターミナルから手動でDrive/Gmailを操作したい | gog |
| GCPなしで定期実行ワークフローを組みたい | Google Apps Script |
| メールとカレンダーだけサクッとCLIで使いたい | gogcli |
まとめ
Google Workspace CLI（gws）は、Workspace全サービスのAPIを1つのCLIツールから操作できるツールです。
Discovery Serviceによる動的コマンド構築、MCPサーバー内蔵、100以上のAIエージェント向けスキル、Model Armorによるセキュリティ対策と、AIエージェント時代を見据えた設計が特徴的です。
セットアップにはOAuth認証の設定が必要で、初回のハードルは低くありません。しかし、一度認証が通れば、Google Workspaceのほぼ全ての操作をターミナルから実行できるようになります。
まずは以下から試してみてください。
npm install -g @googleworkspace/cli
gws auth setup
gws auth login --scopes drive
gws drive files list --params '{"pageSize": 5}'gwsを使った具体的な業務自動化のユースケースは、noteにまとめています。
関連記事
