Google Workspace CLI（gws）とは？インストール・認証・基本的な使い方を解説

Googleドライブ、Gmail、Googleカレンダー、Googleスプレッドシートなどの情報を確認するたびに、それぞれのサービスを開いてログインし、画面を切り替えながら操作する——そんな手間を感じたことはないでしょうか。数件なら問題なくても、複数の予定を一括で取得したい、スプレッドシートの内容を定期的に別のシステムへ連携したいといった場面では、画面操作だけでは限界があります。かといって、APIを使ったプログラムをゼロから書くのはハードルが高い、という方も多いはずです。

そこで活用できるのが、Google Workspace CLI（実行コマンド名：gws）です。Googleドライブ、Gmail、Googleカレンダー、Googleスプレッドシートなど、複数のGoogle WorkspaceサービスをターミナルやPowerShellから操作できるコマンドラインツールで、定型作業の自動化やAIエージェントとの連携にも役立てられます。

ただし、Google WorkspaceのGitHub organizationで公開されているオープンソースツールではあるものの、Googleの公式サポート対象製品ではありません。執筆時点の最新版はv0.22.5（バージョン1.0未満）で、現在も活発に開発が続いています。

この記事では、次の内容を順に解説します。

• Google Workspace CLIとは何か
• 導入前に必要な環境と費用
• OS別のインストール方法
• OAuth認証の手順
• 基本コマンドの使い方
• AIエージェントとの連携方法
• 安全に運用するための注意点

Google Workspace CLI（gws）とは？

Google Workspace CLIは、Google Workspace APIをターミナルのコマンドから操作するためのツールです。コマンド名はgwsで、Apache-2.0ライセンスのもとオープンソースとして公開されています。

内部では、Google Workspace APIのDiscovery Serviceからサービスの仕様情報を取得し、コマンドを動的に構成しています。そのため、APIがアップデートされるとコマンドの内容も追従する設計になっています。実行結果はJSON形式で出力されるため、シェルスクリプトや他のプログラム、AIエージェントへそのまま渡せます。

注意： Google Workspace CLIはGoogleの公式サポート対象外です。バージョン1.0に向けて開発中のため、仕様の変更が入る可能性があります。業務利用時は必ず最新のREADMEとCHANGELOGを確認してください。

Google WorkspaceのサービスをCLIで操作するツール

「CLI」「API」という言葉に慣れていない方のために、まず基本的なイメージを整理します。

CLI（コマンドラインインターフェース）とは、キーボードでコマンドを入力して操作するソフトウェアの形式です。Windowsであればコマンドプロンプトやパワーシェル、Mac・Linuxであればターミナルを通じて使います。

API（アプリケーションプログラミングインターフェース）とは、ソフトウェアとソフトウェアをつなぐ仕組みです。Googleドライブのファイル一覧を外部のプログラムから取得したり、Gmailのメールを別のシステムへ連携したりする際に使います。

Google Workspace CLIは、この2つを組み合わせたツールです。普段ブラウザの管理画面でボタンをクリックして行う操作を、ターミナルへコマンドを入力することで実行できます。gws自体がGoogleのデータを保持しているわけではなく、あくまでGoogle Workspace APIへ処理を依頼する窓口として機能します。

Google Workspace CLIでできることと対応サービス

執筆時点では、主に次のようなサービスと操作に対応しています。

• Googleドライブ：ファイルの検索・取得・アップロード
• Googleスプレッドシート：シートの作成・値の取得・行の追加
• Gmail：メールの取得・送信・検索
• Googleカレンダー：予定の取得・作成
• Google Chat：スペースやメッセージの操作
• Admin SDK：監査ログなどの管理情報の取得

Googleドキュメント、スライド、Google Tasks、People、Classroom、Formsなどに関連するAgent Skills（後述）も用意されています。対応範囲は更新によって変わるため、最新情報は公式リポジトリで確認してください。

管理画面・Apps Script・gcloudとの違い

Google Workspaceを操作する方法はいくつかあります。それぞれの役割を整理すると、目的に合った使い方が見えてきます。

どれか一つですべてを置き換えるのではなく、目的に応じて使い分けるか、組み合わせて活用するのがおすすめです。

Google Workspace CLI（gws）を使う前に必要なものと費用

インストールの前に、必要な環境と費用を確認しておきましょう。

必要なアカウント・ツール・利用環境

基本的に必要なもの

• Googleアカウント
• 操作対象のGoogleサービスを利用できる権限
• Windows、macOS、またはLinuxのパソコン
• PowerShellやターミナル
• OAuth認証に利用するGoogle Cloudプロジェクト

導入方法によって必要になるもの

• gws auth setupを使う場合：Google Cloud CLI
• npmでインストールする場合：Node.js 18以上
• Homebrewでインストールする場合：Homebrew（macOS向け）

Node.js 18以上はnpmを利用する場合の要件です。GitHub Releasesからビルド済みファイルを入手する方法であれば、Node.jsは必須ではありません。

Google Cloudプロジェクトが必要になる理由

Google Workspace CLIを使うには、Google Cloudプロジェクトを通じた認証設定が必要です。主に次の設定に使います。

• Google Workspace APIの有効化
• OAuthクライアントの作成
• OAuth同意画面の設定
• 認証情報やAPI利用状況の管理

gws auth setupコマンドを使うと、Google Cloudプロジェクトの設定やAPIの有効化を対話形式で進められます。ただし、このコマンドを使うにはGoogle Cloud CLIが必要です。

Google Cloud CLIを使わない場合は、Google CloudコンソールのGUIからOAuthクライアントを手動で作成する方法もあります。はじめてGoogle Cloudを触る場合は、手動で設定の流れを確認してから進めると理解が深まります。

利用にかかる費用と個人アカウントでの利用

個人のGoogleアカウントでも、自分が利用できるGoogleドライブやGmailの操作は試せます。ただし、組織のユーザー管理や監査情報など、Google Workspace管理者向けの機能は利用できません。また、個人アカウントでは管理者専用のOAuthスコープを選択しないよう注意が必要です。

Google Workspace CLI（gws）のインストール方法

公式READMEでは、OS・CPUに対応したビルド済みファイルをGitHub Releasesから入手する方法を推奨しています。npmやHomebrewは代替手段として位置づけられています。

Windowsにインストールする

PowerShellを使ってインストールする場合の基本的な流れは以下のとおりです。

1. GitHub Releases から、Windows向けのZIPファイル（google-workspace-cli-x86_64-pc-windows-msvc.zip）をダウンロードする
2. ダウンロードしたZIPファイルを展開する
3. 取り出したgws.exeを、PATHの通ったフォルダへ配置する（例：C:\Tools\gws\ を作成してPATHに追加）
4. 必要に応じて.sha256ファイルを使ってSHA256チェックサムで整合性を確認する
5. PowerShellで gws --help を実行して動作を確認する

執筆時点（v0.22.5）では、専用インストーラー（.msiなど）は配布されておらず、x86_64向けのZIPを手動配置する形が基本です。

npmを使う方法（代替手段）

Node.js 18以上が導入済みであれば、次のコマンドでインストールもできます。

npm install -g @google-workspace-cli/gws

最新バージョンによってパッケージ名が変更される可能性もあるため、GitHub Releasesで確認してから最新版をインストールすることをおすすめします。

macOS・Linuxにインストールする

macOSおよびLinuxでは、次の方法が使えます。

シェルインストーラーを使う（GitHub Releases）

GitHub Releasesで配布されているシェルスクリプトを使うと、自動でバイナリを配置できます。手順はリリースページのREADMEを参照してください。

ビルド済みファイルを手動配置する

CPUアーキテクチャに合ったビルド済みファイルをダウンロードし、/usr/local/binなどPATHの通ったディレクトリへ配置する方法です。

Homebrewを使う（macOS向け代替手段）

brew install googleworkspace-cli

npmを使う（代替手段）

npm install -g @google-workspace-cli/gws

インストールを確認してアップデートする

インストール後は、次のコマンドで動作を確認します。

gws --help

利用できるサブコマンドの一覧と説明が表示されれば成功です。

更新前には必ずGitHub ReleasesやCHANGELOGを確認し、破壊的変更がないかチェックする習慣をつけておきましょう。

初期設定とOAuth認証の手順

インストール後は、GoogleアカウントとのOAuth認証を設定します。

gws auth setupとgws auth loginで認証する

初めて使う場合は、次の流れで進めます。

1. Google Cloud CLIを準備してログインする：gcloud auth login などで認証しておきます
2. gws auth setup を実行する：Google Cloudプロジェクトの選択やAPIの有効化を対話形式で進められます
3. Google CloudプロジェクトとAPIを設定する：利用するサービス（ドライブ、Gmailなど）のAPIをここで有効化します
4. gws auth login を実行する：利用するサービスとOAuthスコープを選んでログインします
5. スコープを選択する：操作するサービス（Drive、Gmail、Sheetsなど）に絞って選択します
6. ブラウザでGoogleアカウントのアクセスを許可する：ブラウザが開くので、画面の指示に従って許可してください

gws auth setupはGoogle Cloud CLIが必要な初回向けのコマンドです。それ以降の認証更新やスコープ変更はgws auth loginで行えます。

用途に合った認証方法を選ぶ

複数の認証情報がある場合の優先順位は、アクセストークン → 認証情報ファイル → 暗号化された認証情報 → 平文の認証情報の順です。

注意： 過去のバージョンでは「ドメイン全体の委任・ユーザー偽装（impersonation）」に関するCLI側の機能がありましたが、現行版では削除されています。古い解説記事の手順をそのまま流用しないよう注意してください。

認証情報とOAuthスコープを安全に管理する

認証情報はAES-256-GCMで暗号化されて保存され、暗号鍵はOSのキーリングへ格納されます。

• 必要なサービスだけを選んでログインする（スコープを最小限に絞る）
• 認証情報ファイルやキーをGitHubや共有フォルダへ置かない
• サービスアカウントのJSONキーを公開リポジトリにコミットしない
• AIへのプロンプトにトークンや秘密鍵を貼り付けない

OAuthアプリがテストモードの場合、選択できるスコープ数に制限があります。最初はDrive、Gmail、Sheetsなど必要なサービスに絞って認証してください。

認証できないときに確認するポイント

基本コマンドと使い方

認証が完了したら、実際にコマンドを試してみましょう。最初は読み取り操作から始め、慣れたら書き込み操作へ進むのがおすすめです。

基本構文とhelp・dry-runの使い方

Google Workspace CLIの基本構文は次のとおりです。

gws サービス リソース メソッド [オプション]

初心者が最初に覚えておくと便利な機能を紹介します。

• --help：利用できるコマンドや引数を確認する（例：gws drive --help）
• --dry-run：APIへ実際に送信する前に、リクエスト内容をターミナルに表示して確認できる
• gws schema：リクエストとレスポンスの形式（スキーマ）を確認できる
• --page-all：複数ページに分かれた結果をまとめて取得する（NDJSON形式で出力）

Googleドライブとスプレッドシートを操作する

Googleドライブの操作例

# ファイル一覧を取得する
gws drive files list

# ファイル名で絞り込んで検索する
gws drive files list --q "name contains '議事録'"

# 特定のファイルのメタデータを取得する
gws drive files get --fileId [ファイルID]

Googleスプレッドシートの操作例

# スプレッドシートの情報を取得する
gws sheets spreadsheets get --spreadsheetId [ID]

# セルの値を取得する
gws sheets spreadsheets values get --spreadsheetId [ID] --range "Sheet1!A1:C10"

GmailとGoogleカレンダーを操作する

Gmailの操作例

# メッセージ一覧を取得する
gws gmail users messages list --userId me

# 条件を指定してメールを検索する
gws gmail users messages list --userId me --q "from:example@example.com"

Googleカレンダーの操作例

# カレンダー一覧を取得する
gws calendar calendarList list

# 予定を取得する
gws calendar events list --calendarId primary --timeMin 2026-07-01T00:00:00Z

メール送信や予定作成などの書き込み操作では、--dry-runで送信前のリクエスト内容を確認する習慣をつけると安心です。

JSON出力をスクリプトやほかのツールで利用する

Google Workspace CLIの実行結果はJSON形式で出力されます。

必要な項目だけ抽出する（macOS・Linux：jqを使う）

gws drive files list | jq '.files[] | {id, name}'

PowerShellで扱う（Windows）

gws drive files list | ConvertFrom-Json | Select-Object -ExpandProperty files

• --page-all でまとめて取得する：NDJSON形式で全件取得できます
• シェルスクリプトへ組み込む：取得したIDを次のコマンドへ渡す処理に活用
• AIエージェントが結果を読み取る：JSON出力をそのままAIへ渡して分析や次の操作を指示する

AIエージェントと連携する方法

Google Workspace CLIは、AIエージェントとの連携を想定して設計されています。

Agent Skillsを使って操作手順をAIへ伝える

Agent Skillsとは、AIエージェントへツールの使い方や操作手順を伝えるためのSKILL.mdファイルです。Google Workspace CLIのリポジトリには、Googleドライブ、Gmail、スプレッドシート、Googleカレンダーなどのサービス別スキルに加えて、メール整理や会議準備などのワークフロー用スキルも含まれています。

このスキルファイルをAIへ読み込ませることで、「どのgwsコマンドを使えばよいか」「どういう順番で実行するか」をAIが理解した上で操作を支援してくれます。

Claude CodeなどのAIツールからコマンドを実行する

AIエージェントからGoogle Workspace CLIを活用する基本的な流れは次のとおりです。

1. AIへAgent Skillsを読み込ませる
2. AIが必要なgwsコマンドを組み立てる
3. ターミナル上でコマンドを実行する
4. JSON形式の結果をAIが読み取る
5. 必要に応じて次の操作を指示する

具体的な活用イメージ

• 今日の予定と未読メールをまとめてブリーフィングする
• 会議前に関連するGoogleドライブのファイルを自動検索する
• GmailのメールからタスクやTODO候補を抽出する
• スプレッドシートの情報をもとにレポートを作成する
• Googleドライブ内のファイルを条件で整理・分類する

Google Workspace公式MCPサーバーとの違い

注意： 過去のバージョンにはgws mcpというMCPサーバーモードが存在しましたが、v0.8.0（PR #275）で削除されています。古い解説記事を参考にしてそのまま実行しようとしても動作しません。必ず現行版のREADMEで確認してください。

MCPサーバーについては「Google WorkspaceのMCPサーバーとは？できること・始め方」の記事で解説しております。

安全に運用するための注意点

まずはテスト環境と読み取り操作から始める

1. テスト用のGoogle Cloudプロジェクトを用意する
2. 必要なAPIだけを有効にする
3. まずファイル一覧や予定一覧の読み取り操作から試す
4. 書き込み操作はテストデータで試してから本番へ展開する
5. 問題がなければ対象の業務範囲を広げていく

権限と認証情報を適切に管理する

• OAuthスコープは必要なサービスだけに絞る（過剰な権限は付与しない）
• 認証情報やキーファイルをGitHubや共有ドライブへ置かない
• 複数人で同じ認証情報を使い回さない
• AIへのプロンプトにトークンや秘密鍵を貼り付けない
• サービスアカウントのJSONキーは厳重に保管する
• 削除・送信・共有設定の変更などの操作には、必ず人の確認工程を入れる
• AIエージェントへ許可するコマンドや操作範囲を限定する

特にAIエージェントに操作させる場合は、読み取りと書き込みを明確に分け、重要な操作は人が確認してから実行する設計が安全です。

仕様変更やアップデートに備える

Google Workspace CLIはバージョン1.0に向けて活発に開発中です。実際にこれまで、MCPサーバーモード（v0.8.0で削除）やドメイン全体の委任・ユーザー偽装機能など、大きな変更が入った経緯があります。

業務で利用する場合は、次の運用習慣をつけておくことをおすすめします。

• 使用中のバージョン番号を記録しておく
• 更新前にCHANGELOGで破壊的変更を確認する
• コマンド例は最新バージョンで再検証してから本番適用する
• 自動化処理はテスト環境で動作確認してから本番へ移す
• エラーが発生したとき、手作業へ戻せる状態を常に残しておく
• 重要な処理をGoogle Workspace CLIだけに依存させない

まとめ

この記事では、Google Workspace CLI（gws）の概要から導入・運用までを解説しました。

• Google Workspace CLIを使うと、Googleドライブ、Gmail、Googleカレンダー、スプレッドシートなどのGoogle Workspace APIをターミナルのコマンドから操作できる
• 導入にはインストールだけでなく、Google CloudプロジェクトとOAuth認証の準備が必要
• JSON形式の出力を活かせば、一括処理やスクリプト、AIエージェントとの連携にも役立てられる
• 一方、Googleの公式サポート対象外で開発中のツールであるため、権限管理と段階的な検証が欠かせない

まずはGitHub ReleasesからGoogle Workspace CLIをインストールして、テスト用アカウントでGoogleドライブのファイル一覧を取得するところから試してみてください。

本番業務への導入を検討する場合は、最新のREADMEとCHANGELOGを確認しながら、段階的に活用範囲を広げていくことをおすすめします。Google Workspace CLIの活用や、Google Workspaceの導入・運用についてお困りの点があれば、お気軽にご相談ください。