gws（Google Workspace CLI）とは？Google Workspace APIをコマンドで操作する使い方・認証と導入判断【v0.22.5】

gwsは、Drive・Gmail・Calendar・Sheets・Docs・ChatといったGoogle Workspace APIを、1つのコマンドからJSONで操作するRust製のCLI（コマンドラインツール）です。GoogleのGitHub組織（googleworkspace/cli）でApache-2.0として公開されていますが、READMEには「公式サポート対象のGoogleプロダクトではない」と書かれています。この記事では、2026年10月20日時点の最新版v0.22.5のバイナリを実際に動かして確かめた出力と終了コードを交えながら、扱えるAPIの範囲、インストール、詰まりやすい認証とスコープ、ヘルパーコマンド、AIエージェント連携、GAMとの使い分け、そして2026年3月から更新が止まっている開発状況をどう判断するかまでを整理します。

まとめ：gwsの要点（2026年10月時点）

• gwsはGoogleのDiscovery Serviceを実行時に読んでコマンドを組み立てるCLIです。メソッドは自動で増えますが、受け付けるサービスは18件で固定されています。
• 最新版はv0.22.5（2026年3月31日）のままです。mainブランチへのコミットもそれ以降なく、2026年10月15日に出た修正PRもマージされずに閉じられました。使うならバージョン固定が前提です。
• Directory APIは登録サービスにありませんが、gws admin-reports:directory_v1 users listのように版を差し替えるとDirectory APIのリクエストが組み立ちます（--dry-runで確認）。ヘルパーもスキルも無い使い方です。
• 導入の推奨はGitHub Releasesのビルド済みバイナリです。Node.js 18以上が要るのはnpm経由で入れる場合だけです。
• gws auth setupはgcloud CLIが無いと終了コード3で止まります。gcloudを入れたくなければ、Cloud ConsoleでDesktopアプリ型のOAuthクライアントを作り、gws auth loginから始めます。
• 未検証（テストモード）のOAuthアプリは同意できるスコープが約25個までです。-s drive,gmail,sheetsのようにサービスを絞ってログインします。
• 会社のWorkspaceアカウントでログインが弾かれる場合は、管理コンソールの「APIの制御」で未設定のサードパーティ製アプリが許可されていない可能性があります。管理者にOAuthクライアントIDを登録してもらいます。
• ドメイン全体の委任（DWD）・なりすましはv0.7.0で削除、gws mcpはv0.8.0で削除されています。他ユーザーのデータを代理で一括処理する用途はGAMの担当です。

gwsの仕組み｜Discovery Serviceによるコマンドの動的生成

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

1. 最初の引数からサービスを特定する（例：drive）
2. そのサービスのDiscovery Documentを取得する（24時間キャッシュ）
3. ドキュメント内のリソースとメソッドからコマンドツリーを構築する
4. 残りの引数を、生成したツリーで改めて解析する
5. 認証してHTTPリクエストを組み立て、実行する

Google側がAPIにメソッドを追加すると、キャッシュが切れた時点（最長24時間後）でgws本体の更新を待たずに呼べるようになります。コマンドはAPIの構造をそのままなぞるので、gws drive files listはdrive.files.listに対応します。SDKを使わずにREST APIを直接呼ぶ場合は、OAuthとページングとエラー処理を書くことになりますが、gwsはこの反復部分を引き受けます。出力は成功もエラーもJSONで、jqで加工したりAIエージェントに読ませたりする前提の設計です。

gwsが扱えるGoogle Workspace APIの範囲

登録済みの18サービスとコマンド名

Discovery Documentから動的に作られるのは、サービスの中のリソースとメソッドです。サービスそのものはソースコードのレジストリで18件に固定されており、v0.22.5でgws admin users listのように未登録の名前を渡すと、Unknown service 'admin'のエラーと終了コード3が返りました。

admin-reportsはAdmin SDKのうちReports API（監査ログと利用状況レポート）です。eventsの実体はWorkspace Events API、workflowはGoogleのAPIではなく複数サービスをまたぐgws独自の機能です。各サービスのメソッドとパラメータはgws <service> --helpやgws schema drive.files.listで引けます。使うAPIがCloudプロジェクトで有効になっていないと、Googleは403（accessNotConfigured）を返し、gwsは有効化用のURLを標準エラーに出します。

Directory APIの呼び出しと版の指定（–api-version）

未登録サービスのエラーメッセージには「unlisted APIは<api>:<version>構文で」と書かれていますが、ソース（main.rsのparse_service_and_version）を読むと、この構文は登録済みサービスの版を上書きするだけです。youtube:v3やgroupssettings:v1は同じエラーで止まりました。

ただしadmin-reportsの実体はAPI名admin（版reports_v1）なので、版をdirectory_v1に差し替えると、ユーザーやグループを扱うDirectory APIのURLが組み立ちます。v0.22.5で認証情報なしに--dry-runで確かめた結果です。

$ gws admin-reports:directory_v1 users list --params '{"customer":"my_customer","maxResults":5}' --dry-run
{
  "body": null,
  "dry_run": true,
  "is_multipart_upload": false,
  "method": "GET",
  "query_params": [["customer","my_customer"],["maxResults","5"]],
  "url": "https://admin.googleapis.com/admin/directory/v1/users"
}

gws reports users list --api-version directory_v1でも同じURLになります（JSONは読みやすく折りたたんでいます）。本番で動かすには、Workspaceの管理者アカウントでgws auth login --scopes https://www.googleapis.com/auth/admin.directory.user.readonlyのようにDirectory用のスコープを明示する必要があります。gwsはadmin.で始まるスコープを推奨候補から外しているためです。この記事では管理者アカウントでの実行までは確かめていません。ヘルパーもAgent Skillsも用意されていない裏道なので、ユーザーの棚卸しなど読み取り中心の用途にとどめ、書き込みは次に述べるGAMに任せるのが安全です。

gwsのインストール｜GitHub Releasesのバイナリが推奨

「npmで入れるツール」と紹介されがちですが、公式が推奨しているのはGitHub Releasesからのビルド済みバイナリ取得で、npmはそのバイナリのダウンロードを自動化する経路です。v0.22.5ではnpmのpostinstallがSHA256チェックサムを検証するようになりました（リリース一覧）。

1. GitHub Releases（推奨）：macOS・Linux（x86_64／aarch64、gnu／musl）・Windows（x86_64）向けのアーカイブがあります。展開したgwsをパスの通った場所に置きます
2. npm：npm install -g @googleworkspace/cli。Node.js 18以上が必要です
3. Homebrew：brew install googleworkspace-cli
4. Nix：nix run github:googleworkspace/cli
5. cargo：cargo install --git https://github.com/googleworkspace/cli --locked

Releasesの各アーカイブには.sha256ファイルが付いています。macOS（x86_64）版で照合した手順です。

gh release download v0.22.5 -R googleworkspace/cli -p 'google-workspace-cli-x86_64-apple-darwin.tar.gz*'
shasum -a 256 google-workspace-cli-x86_64-apple-darwin.tar.gz
cat google-workspace-cli-x86_64-apple-darwin.tar.gz.sha256   # 2行のハッシュが一致すればOK
tar -xzf google-workspace-cli-x86_64-apple-darwin.tar.gz
./gws --version
# gws 0.22.5
# This is not an officially supported Google product.

前提として、OAuthクライアントを作るためのGoogle Cloudプロジェクトと、Workspaceにアクセスできるアカウントが要ります。バイナリを直接置くならNode.jsは不要です。

gwsの認証設定｜gcloud依存・スコープ上限・組織のAPI制御

gwsで最も詰まるのは認証です。ローカル、組織アカウント、CIの順に、引っかかる箇所を確かめていきます。

gws auth setupのgcloud依存と未導入時のエラー

gws auth setup    # 初回だけ。Cloudプロジェクト作成・API有効化・OAuth設定を対話で進める
gws auth login    # スコープを選んでブラウザでログイン
gws auth status   # 認証情報の保存先と状態をJSONで確認

gws auth setupは内部でgcloud CLIを呼びます。gcloudの無い環境で実行すると、次のJSONを出して終了コード3で止まりました。

{
  "error": {
    "code": 400,
    "message": "gcloud CLI not found. Install it from https://cloud.google.com/sdk/docs/install",
    "reason": "validationError"
  }
}

gcloudを入れても、プロジェクトIDが世界中で重複していたり、Google Cloudの利用規約に同意していなかったりするとプロジェクト作成で失敗します。その場合は次の手動セットアップの方が早く終わります。認証情報はAES-256-GCMで暗号化され、鍵はOSのキーリングに置かれます。v0.22.3以降のmacOSとWindowsはOSキーチェーンだけを使い、鍵ファイルへのフォールバックをしません。キーリングの無いLinuxのコンテナやCIではGOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=fileを指定すると、鍵を~/.config/gws/.encryption_keyに保存できます。

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

1. Cloud ConsoleでOAuth同意画面を外部（External）で設定する（試用はテストモードで可。ただし、DriveやGmailへのアクセスに使うリフレッシュトークンは原則7日で失効するため、継続運用前に公開ステータスと認証方式を見直す）
2. テストユーザーに自分のGoogleアカウントを追加する（追加しないと「Access blocked」で弾かれる）
3. 使うAPI（Drive、Gmailなど）を有効にする
4. OAuthクライアントIDをDesktopアプリ型で作る（別の型だとredirect_uri_mismatchになる）
5. ダウンロードしたJSONを~/.config/gws/client_secret.jsonに置き、gws auth loginを実行する

JSONファイルを置く代わりに、環境変数GOOGLE_WORKSPACE_CLI_CLIENT_IDとGOOGLE_WORKSPACE_CLI_CLIENT_SECRETで渡すこともできます。

OAuthスコープの選択とテストモードの個数制限

未検証（テストモード）のOAuthアプリでは、Googleが同意できるスコープを約25個に制限します。v0.22.5のgws auth loginは、指定の仕方で要求するスコープが変わります。

READMEは今も「recommendedプリセットは85個超を含み、未検証アプリでは失敗する」と書いていますが、v0.22.5のソース（auth_commands.rs）では、サービスを絞らないときのRecommendedは上の7個です。25を超えるのは、対話式の選択画面でFull Access相当を選んだときです。--fullで足されるPub/Subとcloud-platformは、ソースのコメントでも未検証アプリでError 403: restricted_clientになるスコープとされています。

gws auth login -s drive,gmail,sheets

スコープを絞るのは回避策であると同時に、最小権限の運用でもあります。トークンが漏えいすると、認証したユーザーの権限と付与したスコープの範囲でデータを読み書きされるおそれがあります。

組織のWorkspaceアカウントのログイン制限と原因の切り分け

個人の@gmail.comでは通るのに会社のアカウントだけ「アクセスがブロックされました」となる場合は、OAuthアプリのテストユーザー登録と、組織のAPIアクセス制御の両方を確認します。組織外のプロジェクトで作成し、管理者がアクセス設定をしていないOAuthクライアントは未設定のサードパーティ製アプリとして扱われ、管理コンソールの［セキュリティ］→［アクセスとデータ管理］→［APIの制御］で「サードパーティ製アプリへのアクセスをユーザーに許可しない」が選ばれていると、ログインできません（Google Workspace 管理者ヘルプ）。

• 対処は、管理者にOAuthクライアントIDをアプリとして追加してもらい、［信頼できる］などのアクセス設定を付けてもらうことです。
• GmailやドライブなどのサービスがAPIの制御で［制限付き］になっていると、［信頼できる］か［特定の Google データ］に設定されたアプリしかそのデータにアクセスできません。
• 設定の反映には最長で24時間ほどかかることがあります。

社内でgwsを配る場合は、OAuthクライアントを1つに決めて管理者が信頼済みに登録し、各自がそのクライアントでgws auth loginする形にすると、利用者と権限を棚卸しできます。

CI/CD・サーバーでの認証とサービスアカウント

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

# 認証済みマシンで
(umask 077; 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）・なりすましのサポートを削除しました（CHANGELOG）。gws auth list、--accountフラグ、GOOGLE_WORKSPACE_CLI_IMPERSONATED_USERも同時に消えました。DWDを設定しても、gws自身には組織ユーザーを指定して委任トークンを発行する機能がありません。外部で適切に発行した委任トークンを渡す構成とは区別してください。gcloudなど別のツールでトークンを発行済みならGOOGLE_WORKSPACE_CLI_TOKENで渡せます。認証情報は次の表の順に検索されます。これらに続くフォールバックとしてApplication Default Credentials（ADC）もあり、環境変数GOOGLE_APPLICATION_CREDENTIALSで指定したファイル、次にgcloudの既定ADCファイルを検索します。

どれが使われているかはgws auth statusのcredential_sourceとstorageで分かります。CI用の鍵は期限も棚卸しもされないまま残りがちなので、サービスアカウントはノンヒューマンアイデンティティ（NHI）として発行・保管・失効まで設計してください。

gwsの基本コマンド｜–params・–json・–dry-runと終了コード

Discovery生成コマンドの書き方とdry-run

URLパラメータは--params、リクエストボディは--jsonにJSONで渡します。--dry-runは認証情報が無くても動き、送るはずのリクエストを表示します。

# 更新日時の新しい順に最大5件のファイル一覧
gws drive files list --params '{"pageSize": 5, "orderBy": "modifiedTime desc"}'

# スプレッドシートを作成
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

gws drive files list --params '{"pageSize": 5}' --dry-runの出力は、"method": "GET"と"url": "https://www.googleapis.com/drive/v3/files"、query_paramsにpageSizeが入ったJSONでした。Sheetsの範囲指定に使う!はbashの履歴展開と衝突するため、値はシングルクオートで囲みます。出力は既定がJSONで、--format table・yaml・csvも選べます。

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

定型作業には、Discovery生成コマンドとは別に手書きのヘルパーがあります。+で始まるのでAPIのメソッド名と衝突しません。

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

+agendaなどの時刻系ヘルパーはGoogleアカウントのタイムゾーンを自動で使い、--timezoneで上書きできます。script +pushはローカルのファイルでApps Scriptプロジェクトを丸ごと置き換えるので、GAS（Google Apps Script）のコードをGitで管理したいときに使えます。注意点として、drive +uploadは共有ドライブのフォルダを指定すると404になる不具合が報告されています（issue #722）。ヘルパーがsupportsAllDrivesを渡さず、--paramsも受け付けないためで、共有ドライブへはgws drive files createに--uploadとsupportsAllDrivesを付けて送ります。

–page-allの取得上限と既定の10ページ制限

--page-allは自動でページを送り、1ページ1行のJSON（NDJSON）を出しますが、既定の--page-limitは10です。全件のつもりで使うと、10ページ分で黙って打ち切られます。全件が要るなら上限を十分に引き上げ、最終ページのnextPageTokenが空であることも確認します。以下の例も最大1000ページで止まります（ページ間の待ち時間--page-delayの既定は100ミリ秒）。

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

gwsの終了コード一覧とCIの分岐条件

失敗の種類は終了コードで分かれており、エラー文字列を解析しなくても処理を分けられます。認証情報なしで実API呼び出しを実行すると"reason": "authError"のJSONと終了コード2、未登録サービスでは終了コード3が返りました。

gwsとAIエージェントの連携｜Agent Skills中心、mcpは削除済み

gwsには一時期gws mcpというMCPサーバー機能があり、ツール定義が200〜400個に膨らむ問題に--tool-mode compact（約26個に圧縮）で対処した経緯もありますが、v0.8.0でコマンドごと削除されました。v0.22.5でgws mcpを実行するとUnknown service 'mcp'になります。現在の連携は次の2つです。

• Agent Skills（SKILL.md）：リポジトリのskills/に95個のスキルが同梱されています（うち業務レシピが41個。READMEの「100+ skills」「50 recipes」は実数と合いません）。npx skills add https://github.com/googleworkspace/cliで導入でき、書式はAgent SkillsのSKILL.md仕様に沿っています。
• CLIの直接実行：エージェントにgwsを実行させ、JSONを読ませます。

READMEはGemini CLIへの導入手順としてgemini extensions install https://github.com/googleworkspace/cliを載せたままですが、Gemini CLIは2026年6月18日に、Googleアカウントでログインする個人の無料枠とGoogle AI Pro・Ultra経由のリクエスト処理を止めています（Google Developers Blog）。有料のAPIキーなら引き続き使えます。後継のAntigravity CLIでは拡張がプラグインとして扱われ、導入済みのGemini拡張はagy plugin import geminiで変換できます（移行ガイド）。経緯はGemini CLI終了の解説にまとめています。gwsのREADMEをagyに更新する提案（issue #958）は2026年10月20日時点で未対応です。

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

# MESSAGE_IDを実在するメールのIDに置き換える
gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID"}' --sanitize "projects/P/locations/L/templates/T"

ヘルプによると--sanitizeにはcloud-platformスコープが必要で、既定のログインでは付きません。GOOGLE_WORKSPACE_CLI_SANITIZE_MODEの既定はwarn（警告だけ）なので、止めるにはblockを明示します。リスクの全体像はOWASP Top 10 for LLMの整理が参考になります。

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

自分のアカウントのDrive・Gmail・Calendarを操作する自動化や、AIエージェントに道具として渡す用途ならgwsが合います。ユーザーの一括作成、グループやOUの変更、全社員のメールボックスへの処理といった管理者業務は、DWDに対応して開発が続くGAM（2026年10月20日にv7.48.31を公開）の担当です。gwsでも版の差し替えでDirectory APIは呼べますが、ヘルパーもスキルも無く、なりすましもできません。gcloudはWorkspace APIを操作するツールではなく、gws auth setupが内部で使う関係です。Apps Scriptは実行時間に上限があり、長いバッチには向きません（GASの解説記事）。実務では「管理者業務はGAM、アプリ連携とエージェントはgws」と分けて使います。社内システムとWorkspaceのつなぎ込みを設計から任せたい場合は、API開発・システム連携でも相談を受けています。

gwsの導入判断｜2026年3月以降の更新停止と採用条件

2026年10月20日にGitHubを確認した時点の状況です。

• リリースとコミット：最新はv0.22.5（2026年3月31日）で、npmのlatestも0.22.5です。mainへのコミットも同日が最後で、約6か月半止まっています。リポジトリはアーカイブされておらず、スターは約3万1,700です。
• PRとissue：認証のキャッシュを修正するPR #959は2026年10月15日に未マージのまま閉じられました。issueは今も報告が続いており、復号に失敗すると標準エラーに警告を出したうえでcredentials.encを削除し、他の認証経路が使えなければ再認証が必要になる不具合（#886、2026年7月28日報告）や、前述の共有ドライブへの+upload（#722）が未解決です。
• サポート：READMEは「公式サポート対象のGoogleプロダクトではない」と明記しています。Googleの組織で開発されていても、サポート契約の対象ではありません。

この状況での判断は次のとおりです。個人やチームの定型作業の自動化、AIエージェントにWorkspaceを触らせる検証には、v0.22.5に固定し、対象操作を検証したうえで、失敗しても復旧できる範囲に限って試用を勧めます（npm install -g @googleworkspace/[email protected]、またはReleasesのバイナリをハッシュ付きで固定）。v0.7.0でDWD、v0.8.0でmcpが消えたように、v1.0前は機能がまとめて削除されることがあります。全社の業務基盤に組み込む用途には勧めません。修正時期が確認できないうえ、#886で報告された認証情報の削除は、代替の認証情報が使えない場合にバッチを止める原因になります。組み込むなら、gws auth statusと終了コード2を監視して再ログインの手順を用意し、代替経路（GAMやクライアントライブラリでの直接実装）を残しておいてください。

始め方は、検証用のCloudプロジェクトでgws auth login -s drive,gmail,sheetsとスコープを絞り、--dry-runでリクエストを確認し、検証用データで実行してから手作業を1つ置き換えるところからです。CIに載せる段階でgws auth exportかサービスアカウントに切り替え、終了コードで失敗を分岐させます。

gwsに関するよくある質問

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

GoogleのGitHub組織（googleworkspace/cli）で開発され、npmでも@googleworkspace/cliとして配布されていますが、READMEとgws --versionの出力に「This is not an officially supported Google product.」と表示されます。Apache-2.0のOSSで、問い合わせ先はGitHubのissueです。

gws auth setup が「gcloud CLI not found」で失敗するのはなぜですか？

gws auth setupはCloudプロジェクトの作成にgcloud CLIを使うためで、gcloudが無いと終了コード3で止まります。gcloudを入れたくない場合は、Cloud ConsoleでOAuth同意画面を設定し、Desktopアプリ型のOAuthクライアントを作って~/.config/gws/client_secret.jsonに置き、gws auth loginを実行してください。

ログイン時にスコープのエラーやアクセスのブロックが出るのはなぜですか？

未検証（テストモード）のOAuthアプリは同意できるスコープが約25個までで、--fullで足されるcloud-platformなどはrestricted_clientで弾かれることがあります。gws auth login -s drive,gmail,sheetsと絞ってください。「Access blocked」はテストユーザー未登録、会社のアカウントだけで出る場合は管理コンソールのAPIの制御が原因であることが多いです。

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

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

gws mcp コマンドが見つからないのはなぜですか？

mcpコマンドはv0.8.0で削除され、v0.22.5ではUnknown service 'mcp'になります。現在は同梱のAgent Skillsを導入し、エージェントにgwsを直接実行させる構成が標準です。

–page-all を付けたのに全件取得できないのはなぜですか？

--page-allの取得上限は既定で10ページです（--page-limitの既定値）。それ以上必要なら--page-limitを引き上げてください。1ページの件数はAPI側のpageSizeで指定します。

関連記事

• GAS（Google Apps Script）とは？できること・制限・始め方を開発者目線で解説
• Agent Skillsとは？SKILL.md仕様と46製品で動かす移植性の実装手順
• Model Armor APIとは？Google Cloudのプロンプト検査の仕組み・料金・実装手順【2026年10月】
• Gemini CLIは終了した？個人向け停止後も使える条件とAntigravity CLI移行手順
• ノンヒューマンアイデンティティ（NHI）とは？機械IDの管理・リスクと実装者向けの守り方を解説【2026年時点】