Google Workspace CLI（gws）の使い方｜インストールからGmail・Drive・Calendar操作まで
Google公式CLI「gws」のインストール方法と使い方を解説。npm一発で導入でき、Gmail送信・Driveファイル操作・Calendar管理がコマンド1行で完結する。2026年最新。
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"}'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 # ワークフローツールも含める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呼び出しを自動で組み合わせます。
MCPツール数の上限に注意。 -s all で全サービスを公開すると、サービスあたり10〜80個のツールが登録され、合計で数百ツールになります。MCPクライアントの多くはツール数50〜100が実用的な上限で、それを超えるとレスポンスが遅くなったり、ツール選択の精度が落ちます。普段使いなら -s drive,gmail,calendar 程度に絞るのが現実的です。
--tool-modeの使い分けやワークフローツール、Agent Skills、セキュリティ設定まで含めた実践的な設定ガイドは、別記事で詳しく解説しています。
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との統合が組み込まれています。
# 個別リクエストでサニタイズ
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またはblockOAuthセットアップで絶対ハマるポイント
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環境では不安定な報告があり、その場合は手動セットアップ一択です。
セキュリティとトラブルシューティング
セキュリティ上の注意点
OAuthスコープは最小限に。 トークン漏洩時の被害範囲を最小化するために、必要なサービスだけに権限を絞ります。
gws auth login --scopes drive,calendar # 推奨
gws auth login --scopes recommended # 非推奨: 全サービスに権限付与認証情報ファイルの管理。 gws auth exportで書き出すファイルにはリフレッシュトークンが含まれます。CI/CD環境ではVault、AWS Secrets Manager等で管理してください。
公式サポート外のリスク。 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にまとめています。
関連記事
