gws（Google Workspace CLI）とは？Google Workspace APIをコマンド1本で操作する使い方と導入判断

gwsは、Drive・Gmail・Calendar・Sheets・Docs・ChatといったGoogle Workspace APIを単一のコマンドから操作するRust製のCLIです。GoogleのGitHub組織（googleworkspace/cli）で開発され、Apache-2.0で公開されています。特徴は、コマンド一覧を静的に持たず、Googleが公開するDiscovery Serviceを実行時に読んでコマンド体系をその場で組み立てる点。この記事では、扱えるAPIの範囲から、インストール、つまずきやすい認証（25スコープ制限）、実務で効くヘルパーコマンド、CI/CDでの使い方、GAMやgcloudとの使い分けまでを公式リポジトリの一次情報にもとづいて整理します。

まとめ：gwsの要点

• gwsはGoogle Workspace APIを1つのCLIに束ねるRust製ツール。Discovery Documentを実行時に取得（24時間キャッシュ）してコマンドを動的生成するため、APIにメソッドが増えれば自動的に呼べるようになる。
• GoogleのGitHub組織で開発されているが、READMEに「公式サポート対象のGoogleプロダクトではない」と明記。本記事執筆時点（2026年7月）の最新はv0.22.5（2026年3月31日）で、v1.0到達前・破壊的変更ありの段階。
• 推奨インストールはGitHub Releasesのビルド済みバイナリ。npm・Homebrew・Nix・cargoも使える。npm経由の場合だけNode.js 18以上が必要。
• 最初の壁は認証。gws auth setupはgcloud CLIに依存し、未検証（テストモード）のOAuthアプリにはスコープ約25個の上限があるため、85個超を含むrecommendedプリセットは失敗する。-s drive,gmail,sheetsとサービスを絞るのが正解。
• サービスアカウントによる「ドメイン全体の委任（DWD）」やユーザーなりすましは、v0.7.0で機能ごと削除された。組織ユーザーのメールやドライブを代理操作する用途は、現在のgwsでは実現できない。
• 全レスポンスが構造化JSON。--dry-runでリクエストを事前確認でき、終了コードが0〜5で意味づけされているためCIで失敗の種類ごとに分岐できる。
• Gmailの+sendやCalendarの+agendaなど+接頭辞のヘルパーコマンドがあり、定型作業はDiscovery生成コマンドより短く書ける。
• gws mcp（MCPサーバー機能）はv0.8.0で削除済み。現在のAIエージェント連携は「CLIの直接実行＋Agent Skills（SKILL.md）」が主軸で、Gemini CLIには拡張として導入できる。

gwsの仕組み｜コマンド一覧を持たず、Discovery Serviceから毎回組み立てる

一般的なCLIは、対応コマンドをソースコードに静的に持ちます。gwsはこれをやめ、Google API Discovery Serviceが配信する各APIの機械可読な定義（Discovery Document）を実行時に取得し、そこからコマンドツリーを生成します。公式READMEが説明する処理は次の5段階です。

1. argv[1]を読んでサービスを特定する（例：drive）
2. そのサービスのDiscovery Documentを取得する（24時間キャッシュ）
3. ドキュメント内のリソースとメソッドからclap::Commandのツリーを構築する
4. 残りの引数を、生成したツリーで再パースする
5. 認証してHTTPリクエストを組み立て、実行する

この「2段階パース」により、Google側がAPIにメソッドを追加した場合も、gws本体の更新を待たずキャッシュ失効後（最長24時間）には新しいメソッドが呼べます。REST APIを自前で叩く実装では、サービスごとにSDKを入れ、OAuthフローとページングとエラー処理を書き直すことになりますが、gwsが省いてくれるのはまさにこの反復部分です。コマンド体系はAPIの構造そのままなので、Google APIの命名を知っていれば迷いません（gws drive files list＝drive.files.list）。

出力は成功・エラー・ダウンロードのメタデータまですべて構造化JSON。jqで加工したり、LLMエージェントに読ませたりする前提の設計です。

gwsが扱えるGoogle Workspace APIの範囲

誤解しやすい点ですが、Discovery Documentから動的生成されるのはサービス内のリソースとメソッドであって、サービスそのものは無制限ではありません。gwsが受け付けるサービスはソースコードのレジストリで18件に固定されており、ここに無いサービス名を渡すと未知のサービスとして終了コード3で落ちます。

実務で効く注意点が3つあります。ひとつめは管理系の範囲で、admin-reportsが指すのはAdmin SDKのうちReports API（監査ログと利用状況レポート）だけです。ユーザー・グループ・OU・ライセンスを操作するDirectory APIはレジストリに無く、gwsではユーザーの一括作成のような管理者業務ができません。これが後述するGAM併用の最大の理由です。ふたつめはeventsで、実体はWorkspace Events API（Discovery上の名称はworkspaceevents v1）です。みっつめはworkflow（別名wf）で、これはGoogleのAPIではなく複数サービスをまたぐgws独自の擬似サービスです。

各サービスで使えるメソッドとパラメータはgws <service> --helpやgws schema drive.files.listで引けます。使いたいAPIがGCPプロジェクトで有効化されていない場合、Googleは403（accessNotConfigured）を返し、gwsは有効化用のURLを標準エラーに出してくれます。

インストールと前提条件｜npmだけではない5つの導入経路

「npmで入れるツール」と紹介されがちですが、公式が推奨しているのはGitHub Releasesからのビルド済みバイナリ取得です。npmはそのバイナリのダウンロードを自動化する経路という位置づけになります（v0.22.4でcargo-distを外し、npmインストーラはネイティブfetchへ移行）。

1. GitHub Releases（公式推奨）：OS・アーキテクチャ別のアーカイブをダウンロードして展開し、gwsバイナリをパスの通ったディレクトリに置く
2. npm：内部でGitHub Releasesのバイナリを取得する。Node.js 18以上が必要
3. Homebrew（macOS／Linux）
4. Nix
5. cargo（ソースからビルド）

npm install -g @googleworkspace/cli

brew install googleworkspace-cli

nix run github:googleworkspace/cli

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

前提条件は、OAuthクレデンシャル用のGoogle Cloudプロジェクト、Google Workspaceにアクセスできるアカウント、そしてnpm経由の場合のみNode.js 18以上です。バイナリを直接置くならNode.jsは不要で、この点は「Node.jsが必須」と書かれた解説との重要な差分になります。

認証設定｜gws auth setupはgcloud必須、25スコープ制限が最初の壁

GSCの実クエリでも「gws auth setup」「gws auth export」が上位に来るとおり、gwsで最もつまずくのは認証です。用途別に4つの経路があります。

ローカル（対話）：gws auth setup と gws auth login

gws auth setup    # 一度だけ。Cloudプロジェクト作成・API有効化・ログインまで面倒を見る
gws auth login    # 以降のスコープ選択とログイン
gws drive files list --params '{"pageSize": 5}'

注意点はgws auth setupがgcloud CLIに依存していることです。gcloudが無い環境では動きません。gcloudを入れるか、次の手動セットアップに切り替えるかの二択になります。取得した認証情報はAES-256-GCMで暗号化して保存され、鍵はOSのキーリングに置かれます。v0.22.3以降、macOSとWindowsではOSキーチェーンを厳格に使い、.encryption_keyファイルへのフォールバックを行いません。キーリングが使えないLinuxのDockerやCI環境では、GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=fileを指定すると~/.config/gws/.encryption_keyにファイル保存できます。

gcloudを使わない手動OAuthセットアップ

1. Cloud ConsoleでOAuth同意画面を外部（External）で設定する（テストモードのままで可）
2. テストユーザーに自分のGoogleアカウントを追加する（未追加だとログインが403で弾かれる）
3. 使うAPI（Drive、Gmailなど）を有効化する
4. OAuthクライアントIDをDesktopアプリ型で作成する（別の型で作るとredirect_uri_mismatchになる）
5. ダウンロードしたJSONを~/.config/gws/client_secret.jsonに置き、gws auth loginを実行する

つまずきポイント：テストモードの25スコープ上限

OAuthアプリが未検証（テストモード）の場合、Googleは同意できるスコープを約25個に制限します。一方、gwsのrecommendedスコーププリセットは85個超を含むため、そのまま選ぶと同意画面がエラーになります（特に@gmail.comアカウント）。回避策はサービス単位で絞ることです。

gws auth login -s drive,gmail,sheets

-sは--scopesの短縮形で、どちらで書いても同じです。これは単なる回避策ではなく、最小権限の原則としても正しい運用です。85個のスコープを全許可したトークンは、漏えい時にWorkspace全域を触れる鍵になります。

CI/CD・サーバー：エクスポートとサービスアカウント

ブラウザのない環境では、対話ログイン済みのマシンで認証情報を書き出し、実行環境へ渡します。

# 認証済みマシンで
gws auth export --unmasked > credentials.json

# ヘッドレス環境で
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list

サーバー間連携では、サービスアカウントの鍵ファイルを同じ環境変数に指定すればログイン不要で動きます。ただし操作できるのはサービスアカウント自身に権限があるリソースだけです。gwsはv0.7.0でマルチアカウント・ドメイン全体の委任（DWD）・なりすましのサポートを削除しており（gws auth list、gws auth default、--accountフラグ、GOOGLE_WORKSPACE_CLI_IMPERSONATED_USERなどが同時に廃止）、DWDを設定しても組織ユーザーになりすました一括処理はできません。その用途は後述のGAMなど別ツールの担当です。gcloudなど他ツールが既にトークンを発行している環境ではGOOGLE_WORKSPACE_CLI_TOKENを使えます。認証情報の優先順位は次のとおりです。

CI用の鍵は、期限も棚卸しもされないまま放置されがちです。サービスアカウントのような機械IDはノンヒューマンアイデンティティ（NHI）として扱い、発行・保管・失効の運用まで含めて設計してください。

基本コマンドの書き方｜–params・–json・–dry-runとgws schema

Discovery生成コマンドの型

URLパラメータは--params、リクエストボディは--jsonで渡します。事前確認の--dry-runと、スキーマを引くgws schemaが効きます。

# 直近5件のファイル一覧
gws drive files list --params '{"pageSize": 5}'

# スプレッドシートを作成
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# 実行せずリクエスト内容だけ確認
gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}' --dry-run

# メソッドのリクエスト・レスポンス構造を引く
gws schema drive.files.list

Sheetsのレンジ指定に使う!はbashの履歴展開と衝突するため、値は必ずシングルクオートで囲むのが公式の注意事項です。

ヘルパーコマンド（+接頭辞）を使う

定型作業には、Discovery生成コマンドとは別に手書きのヘルパーが用意されています。+接頭辞で区別され、API側のメソッド名と衝突しません。gws gmail --helpのように実行すると、生成コマンドとヘルパーが並んで表示されます。

なおgmail +read（メール本文やヘッダーの抽出）はREADMEのヘルパー一覧に載っていませんが、ソースにもスキル索引にも存在します。workflowはGoogleのAPIではなくgws独自のクロスサービス機能で、+standup-reportは当日の会議と未完了タスクを朝会用に要約し、+meeting-prepは次の会議のアジェンダ・出席者・関連ドキュメントを揃えます。+agendaなどの時刻系ヘルパーはGoogleアカウントのタイムゾーン（Calendar設定APIから取得し24時間キャッシュ）を自動で使い、--timezoneで上書きできます。script +pushはローカルのファイルでApps Scriptプロジェクトを丸ごと置き換えるもので、GAS（Google Apps Script）のコードをGit管理したいときに効きます。

gws gmail +send --to [email protected] --subject "Hello" --body "Hi there"
gws calendar +agenda --today --timezone America/New_York
gws workflow +standup-report

落とし穴：--page-allは既定で10ページまで

--page-allは自動ページングしてページごとに1行のJSON（NDJSON）を吐きますが、既定の--page-limitは10です。「全件取れる」と思い込んだまま大量データを扱うと、静かに10ページ分で打ち切られます。全件が必要なら上限を明示してください（--page-delayの既定は100ミリ秒）。

gws drive files list --params '{"pageSize": 100}' --page-all --page-limit 1000 | jq -r '.files[].name'

終了コードでCIを分岐する

エラー文字列をパースしなくても、失敗の種類で処理を分けられます。

AIエージェント連携｜mcpコマンドはv0.8.0で削除された

gwsには一時期gws mcpというMCP（Model Context Protocol）サーバー機能があり、200〜400個のツール定義をエージェントへ露出していました。ツール数がコンテキストを圧迫する問題への対処として、1サービス1ツール＋メタツールに畳む--tool-mode compact（約26ツールに削減）が入った経緯もありますが、最終的にv0.8.0でmcpコマンド自体が削除されました。「gws mcp が動かない」という検索が残っているのはこのためです。

現在の連携方法は次の2本柱です。

• Agent Skills（SKILL.md）：リポジトリのskills/配下に95個のスキルディレクトリが同梱されています（内訳はサービス・ヘルパー・職種別ペルソナが54、業務レシピが41。READMEの「100+ skills・50 recipes」やバッジの「40+」は表記が揺れているため、実測値で示しています）。npx skills add https://github.com/googleworkspace/cliで一括導入でき、サブディレクトリを指定すれば必要な分だけ入れられます。書式の考え方はClaude SkillsのSKILL.mdと同じです。
• CLIの直接実行：エージェントにgwsを叩かせ、構造化JSONを読ませます。Gemini CLIにはgemini extensions install https://github.com/googleworkspace/cliで拡張として導入でき、gws側の認証をそのまま継承します。OpenClawではスキルディレクトリをシンボリックリンクする運用が案内されています。

エージェントにメールやドキュメントを読ませる構成では、本文に仕込まれた指示をエージェントが実行してしまうプロンプトインジェクションが現実的なリスクになります。gwsはGoogle CloudのModel Armorと連携し、APIレスポンスをエージェントへ渡す前に検査できます。

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

既定のGOOGLE_WORKSPACE_CLI_SANITIZE_MODEはwarn（警告のみ）で、遮断するにはblockを明示します。入れただけでは止まりません。リスクの全体像はOWASP Top 10 for LLMの整理が参考になります。

GAM・gcloud・Apps Scriptとの使い分け

Google Workspaceを扱うツールは複数あり、守備範囲が違います。

アプリ連携・自動化スクリプト・AIエージェント連携ならgwsが第一候補ですが、後述のとおりv1.0前のためバージョン固定が前提です。管理者オペレーション（ユーザーの一括作成、他ユーザーのデータ操作）は、gwsがDirectory APIを持たずDWDも削除している以上、原理的に守備範囲外です。ここはDWDとなりすましに対応しGoogleのAPIを長く追ってきたGAM（GAM-team/GAM、2014年から開発が続くPython製）の担当になります。gcloudはWorkspace API操作用のツールではなく、gwsのauth setupが内部で依存する関係にあります。Apps Scriptは実行時間の上限があり長時間バッチには向きません（詳細はGASの解説記事）。実務では「管理者業務はGAM、アプリ・エージェント連携はgws」という併用が落としどころです。

導入判断｜v1.0前の破壊的変更をどう受け止めるか

採用を検討する際に確認すべき前提は3つです。

• 「公式サポート対象のGoogleプロダクトではない」とREADMEが明記している。GoogleのGitHub組織で開発され、スター数も約3万に達していますが、サポート契約の対象ではありません。稟議ではここを曖昧にしないほうが安全です。
• v1.0前で破壊的変更が予告されている。実際にDWD・なりすましはv0.7.0で、mcpコマンドはv0.8.0で削除されました。本番運用ではnpm install -g @googleworkspace/[email protected]のようにバージョンを固定し、更新時はCHANGELOGを読んでから上げる運用が必須です。
• 更新ペースを見ておく。最新は2026年3月31日のv0.22.5で、本記事執筆時点（2026年7月）まで約3か月半、mainブランチへのリリースもコミットも出ていません。作業ブランチには2026年7月1日時点のpushがあり、リポジトリもアーカイブされていない（開発終了の告知もない）ため停止と断ずることはできませんが、採用前に最新の動きは必ず確認してください。

現実的な始め方は、検証用のGCPプロジェクトで-s drive,gmail,sheetsとスコープを3サービスに絞ってgws auth loginし、まず--dry-run付きで既存の手作業を1つ置き換えることです。CIへ載せる段階でgws auth exportかサービスアカウントに切り替え、終了コードで失敗を分岐させれば、既存パイプラインへ無理なく組み込めます。

gwsに関するよくある質問

gwsはGoogle公式のツールですか

GoogleのGitHub組織（googleworkspace/cli）で開発され、npmでも@googleworkspace/cliとして配布されていますが、READMEには「公式サポート対象のGoogleプロダクトではない」と明記されています。Apache-2.0のオープンソースであり、サポート窓口はGitHubのIssueになります。

gws auth setup が「gcloud not found」で失敗します

gws auth setupはプロジェクト作成を自動化するためにgcloud CLIを呼び出します。gcloudを入れたくない場合は、Cloud ConsoleでOAuth同意画面を設定し、Desktopアプリ型のOAuthクライアントを作成してクレデンシャルを手動で配置してください。型を間違えるとredirect_uri_mismatchが発生します。

ログイン時にスコープのエラーが出るのはなぜですか

未検証（テストモード）のOAuthアプリは同意できるスコープが約25個までに制限される一方、recommendedプリセットは85個超を含むためです。gws auth login -s drive,gmail,sheetsのように必要なサービスだけ指定すれば解消します。「Access blocked」や403が出る場合は、OAuth同意画面のテストユーザーに自分のアカウントを追加してください。

サービスアカウントで他ユーザーのGmailやドライブを操作できますか

できません。gwsはv0.7.0でドメイン全体の委任（DWD）・なりすまし・マルチアカウントのサポートを削除しました。サービスアカウントで動かせるのは、そのアカウント自身に共有・権限があるリソースだけです。組織ユーザーの代理操作が必要なら、GAMなどDWDに対応したツールを使ってください。

gws mcp コマンドが見つかりません

mcpコマンドはv0.8.0で削除されました。現在は、同梱のAgent Skills（SKILL.md）を導入したうえでエージェントにgwsを直接実行させる構成が標準です。Gemini CLIであればgemini extensions installで拡張として導入できます。

–page-all を付けたのに全件取得できません

--page-allの既定の取得上限は10ページです（--page-limitのデフォルト値）。それ以上必要な場合は--page-limitを明示的に引き上げてください。1ページあたりの件数はAPI側のpageSizeで指定します。

関連記事

• GAS（Google Apps Script）とは？できること・制限・始め方を開発者目線で解説：gwsと並ぶWorkspace自動化の選択肢。実行時間の上限など、CLIへ移すべき境界がわかります。
• Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】：gwsが同梱するAgent Skillsと同じSKILL.md形式の書き方を解説しています。
• OWASP Top 10 for LLMとは？2025年版の全10項目と変更点・実務での対策：Model Armorで防ごうとしているプロンプトインジェクションの位置づけを確認できます。
• ノンヒューマンアイデンティティ（NHI）とは？機械IDの管理・リスクと実装者向けの守り方を解説【2026年時点】：CI/CDで使うサービスアカウント鍵の管理設計に直結します。