Google Workspace CLI（gws）でターミナルからDriveやGmailを操作する

gcloudとgwsの関係：下回りはgcloud、上にWorkspace専用レイヤー

まず押さえておきたいのは、gwsは「gcloudのラッパー」ではなく、 Google Workspace API専用の汎用クライアントだという点です。

gcloudはGCEやCloud Storage、Cloud RunなどGCP全体を管理するための公式CLIですが、gwsはDriveやGmail、Calendar、Sheets、Docs、Chat、AdminといったWorkspaceのREST APIをコマンドから叩きやすくすることに特化しています。

実際には、gwsのセットアップフローの中で、gcloud projects createやAPIの有効化などを内部的に呼び出してくれるため、 「インフラ周りの初期設定はgcloud」「その上で、日々のWorkspace操作や自動化はgws」という役割分担になります。

インストールと初期セットアップ（Windows想定）

公式READMEでは、もっともシンプルな導入手順として次の2行が紹介されています。

npm install -g @googleworkspace/cli
gws auth setup

2行目のgws auth setupを実行すると、gcloudでログイン済みのGoogleアカウントを検出し、 どのアカウントでWorkspace用のGCPプロジェクトを作成するか、対話形式で聞いてきます。

次に、gws用のGCPプロジェクトを新規作成するか、既存プロジェクトを使うかを選びます。 記事では、既存の本番プロジェクトと分離するために、gws-cli-yosuke-1234 のような専用プロジェクトを新しく作成しました。

さらにウィザードが進むと、Drive / Gmail / Calendar / Docs など、どのWorkspace APIを有効にするかを選ぶ画面になります。 必要なサービスだけをONにしておくことで、権限を絞りつつ、用途に合わせた最小構成のCLI環境を用意できます。

コンセント画面とOAuthクライアントの手動設定

今回は、自動作成ではなく、GCPコンソール側でOAuthクライアントを手動で作るルートになりました。
まずはGoogle Auth Platformの概要画面から「開始」を押して、ユーザータイプやアプリ情報を外部向けとして設定します。

そのうえで、API とサービス > 認証情報 から「認証情報を作成」ボタンを押し、OAuth クライアント ID を選択します。
アプリケーションの種類は「デスクトップ アプリ」を選べば、gws が期待している設定になります。

ウィザードに沿って進めると、「クライアント」タブの中でDesktopアプリ用のOAuthクライアントが作成されます。
画面上部には、アプリケーションの種類と名前、下部にはクライアント ID とクライアント シークレットが表示されます。

最後に表示されるダイアログで、クライアント ID とクライアント シークレットをコピーします。
ターミナル側の gws auth setup が求めている入力欄に貼り付ければ、gws 側のOAuth設定が完了します。

超重要：テストユーザーに登録しないと「gws_test_account エラー403」で弾かれる

ここが一番ハマりやすいポイントです。gwsが作ったOAuthアプリはデフォルトで「テスト中」の状態になっています。
OAuth同意画面の「テストユーザー」に登録されたアカウントだけがログインを通過できます。
ここに自分のGoogleアカウントを追加しないと、ブラウザ側で403エラーになり、いくらやり直しても先に進みません。

もしこの設定を忘れていると、ブラウザでログインを試みたときに、
「このアプリはGoogleで確認されていません」「gws_test_account は Google の審査プロセスを完了していません」
といった警告が表示され、エラー 403: access_denied でブロックされます。

対策はシンプルで、先ほどのテストユーザー画面で自分が使いたいアカウントを追加してから、再度 gws auth login を実行するだけです。
これで403を回避し、ブラウザで権限を許可すれば、ターミナル側に認証完了メッセージが表示されるようになります。

実際に何ができるのか

gwsのコマンドは、基本的に gws <サービス> <リソース> <メソッド> という構造になっています。
しかも、コマンド一覧は静的にハードコードされておらず、 Google Discovery ServiceからREST APIの定義を読み込んで動的に生成されています。

• Drive：gws drive files list --params '{"pageSize": 10}' で最近のファイル一覧、--upload付きでファイル作成＋アップロード
• Sheets：gws sheets spreadsheets create --json '{"properties":{"title":"Q1 Budget"}}' で新しいスプレッドシートを作成
• Chat：gws chat spaces messages create ... --json '{"text":"Deploy complete."}' --dry-run でChatメッセージ送信のプレビュー
• Gmail / Calendar / Admin：REST APIにあるエンドポイントは、ほぼそのままCLIサブコマンドとして利用可能

すべてのレスポンスはJSONで返ってきます。
jqでフィルタしてログに保存したり、スクリプトから定期実行したり、 あるいはAIエージェントから「Driveの特定フォルダの一覧を取ってほしい」といった形で呼び出すことができます。

重要：使いたいWorkspace APIはGCP側で「有効」にする必要がある

gwsからDriveやGmailなどのAPIを叩くときは、GCPコンソール側で該当APIを「有効」にしておくことが必須です。
まだ有効化していない状態で実行すると、403エラーとともに「API not enabled for your GCP project.」というメッセージと、有効化用URLが表示されます。

実運用では、まずgwsで一度コマンドを叩いてみて、403とともに表示される enable_url にアクセスして「有効にする」をクリックし、数十秒待ってから再実行する流れがわかりやすいと感じました。 利用したいサービスごとに、この有効化ステップが必要だと覚えておくとスムーズです。

一連のターミナル操作の流れ（抜粋・ID等はマスク）

実際に手元で行ったセットアップ〜Drive一覧取得までの流れを、最低限のログだけ抜き出すと次のようになります。 クライアントIDやファイルIDなどの個人情報・識別子は****でマスクしています。

PS > npm install -g @googleworkspace/cli

PS > gws auth setup
...（ウィザードに従って GCP プロジェクトと OAuth クライアントを作成）...

PS > gws auth login --account yosuke4061@gmail.com
Open this URL in your browser to authenticate:
  https://accounts.google.com/o/oauth2/auth?...client_id=****.apps.googleusercontent.com&...
{
  "account": "yosuke4061@gmail.com",
  "credentials_file": "C:\\Users\\...\\gws\\credentials.****.enc",
  "message": "Authentication successful. Encrypted credentials saved.",
  "status": "success"
}

PS > gws auth list
{
  "accounts": [
    {
      "email": "yosuke4061@gmail.com",
      "is_default": true
    }
  ],
  "count": 1,
  "default": "yosuke4061@gmail.com"
}

PS > gws drive files list --params '{\"pageSize\": 5}'
{
  "files": [
    { "id": "****", "name": "自由形式 2", ... },
    { "id": "****", "name": "埼玉県の巨木一覧 (203/205地点)", ... },
    { "id": "****", "name": "Competitor_Analysis", ... },
    { "id": "****", "name": "無題の図形描画", ... },
    { "id": "****", "name": "Gemma LoRA ファインチューニング.ipynb", ... }
  ],
  "kind": "drive#fileList",
  "nextPageToken": "****"
}

おおまかな流れとしては「npm install → gws auth setup → gws auth login --account ... → 必要なAPIを有効化 → 実際の gws drive ... コマンド」という順番で進めれば、 ターミナルからGoogle Workspaceを扱えるところまで到達できます。

（おまけ）強制アンインストール用 PowerShell（ダウンロード）

「PowerShellでゴリゴリに、強制アンインストールしたい」方向けに、gwsの削除スクリプトをZIPで置いておきます。 実行は自己責任で、内容を確認してから使ってください（認証情報フォルダも削除します）。

PS > Expand-Archive .\gws-uninstall.zip -DestinationPath .\gws-uninstall -Force
PS > powershell -ExecutionPolicy Bypass -File .\gws-uninstall\gws-uninstall.ps1

AIエージェントとの連携と注意点

公式リポジトリには、各WorkspaceサービスごとのSKILL.mdや、gwsをMCPサーバーとして動かすための仕組みも同梱されており、 Gemini CLIや他のエージェント環境から「Driveツール」「Gmailツール」として呼び出せる設計になっています。 ただしREADMEに明記されているとおり、「This is not an officially supported Google product.」とあるため、 仕事や本番環境で使う場合は、権限設計と監査ログ、バージョン固定などを自分側でしっかり管理する前提になります。