Google Workspace CLIを利用する上で最低限気を付けたいポイント

はじめに

こんにちは。
クラウド事業本部コンサルティング部の渡邉です。

先日、Google Workspaceをコマンドラインから操作できるGoogle Workspace CLIが登場し、ターミナルからgwsコマンドを利用してDrive、Gmail、Calendarなどを直接操作できるようになりました。
Google Workspace CLIの概要や初期設定等についてはこちらのブログ記事をご確認いただけると幸いです。

https://dev.classmethod.jp/articles/google-workspace-cli-release/

また、Google Workspace CLIをClaude Codeと連携させて操作させてみたブログ記事もございますので、こちらもチェック頂けると幸いです。

https://dev.classmethod.jp/articles/google-workspace-cli-gws-launch-try-claude-code/

Google Workspace CLIの登場により、Claude CodeなどのAIエージェントを利用してGoogle Workspace上のGmailやDrive、Spreadsheetを簡単に操作することが可能になります。しかし、GmailやDrive、SpreadsheetなどのGoogle Workspace上に存在するアプリケーションには、大切なデータが存在していたり、一つの操作ミスで情報漏洩につながったりする恐れもあります。
Google Workspace APIにアクセスする以上、認証情報の管理やスコープの選択など、セキュリティ面の考慮が必要になることを意識して利用する必要があると思います。

今回は、Google Workspace CLIを利用する上で最低限気を付けたいポイントを整理してみました。

操作に必要なAPIのみを有効化する

Google Workspace CLIの初期セットアップ時にgws auth setupコマンドを実行することで、以下のように対話的に設定を行ってくれます。

• Step1 : gcloud CLI
• Step2 : Authentication
• Step3 : GCP Project
• Step4 : Workspace API
• Step5 : OAuth Credentials

その際に、Step4 : Workspace APIでStep3 : GCP Projectで選択したGoogle Cloud Project内で、どのGoogle WorkspaceサービスのAPIを有効化するのか選択します。
まずこの時に、必要なAPIのみ有効化し、不必要なAPIは有効化しないことが大切になります。
また、すでに有効化しているAPIの中でユーザが実現したい操作に不必要なAPIがあるのであれば、Google Cloudコンソールから手動で無効化することを検討してください。

Google Cloudコンソールから手動で無効化するには以下の手順を実行してください。

• Google Cloudコンソールにアクセス
• 【APIとサービス】->【有効なAPIとサービス】をクリック

• 無効化したいAPIを検索し、【APIを無効にする】をクリック

• 【無効にする】をクリック

Google Workspace CLIは有効化されたWorkspace APIのサービスのみしか操作することができません。例えば、APIが有効化されていないGmailの操作を以下のようにAIエージェントが実行してしまった場合でも、APIが有効化されていなければ、そもそもアクセスすることができないため誤操作を防止することができます。

gws gmail users messages list --params '{"userId": "me", "maxResults": 10, "q": "is:inbox"}' --format json 2>&1

{
  "error": {
    "code": 403,
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=**********",
    "message": "Gmail API has not been used in project ********** before or it is disabled. Enable it by visiting https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=********** then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "reason": "accessNotConfigured"
  }
}

これがまず最低限意識する点になります。

必要な操作のみを実現するOAuthスコープを選択する

操作に必要なAPIのみを有効化した後は、gws auth loginコマンドを利用することで、以下の画像のようにOAuthのスコープを選択することができます。

そもそもOAuthスコープとは？

OAuthスコープは、アプリケーション（この場合はGoogle Workspace CLI）がユーザーのどのデータに、どの範囲でアクセスできるかを定義する仕組みになります。
gws auth loginコマンド実行時にスコープを選択すると、そのスコープに応じたトークンが発行されます。例えば、Google Driveの場合は以下のようになります。

• drive.file を選択 → アプリケーション（この場合はGoogle Workspace CLI）が作成/開いたファイルのみ操作可能
• drive を選択 → Google Drive上の全ファイルの読み書き削除が可能

同じGoogle Driveに対するアクセスでも、スコープによって操作することができる範囲が大きく異なることを理解しておく必要があります。
Google Workspace CLIで使うスコープは必要最小限にすべきです。例えば、特定ファイルの操作ならdrive.fileを使い、driveは避けるようにして最小権限の原則を徹底しましょう。

混同しやすいスコープに注意

スコープ名だけでは実際の権限範囲が分かりにくいケースがあります。以下は特に混同しやすい例です。

そういった場合は、gws schemaコマンドでスコープを確認しましょう。
Google Workspace CLIには、APIメソッドの仕様を確認できるgws schemaコマンドが用意されています。このコマンドを使うと、特定のAPIメソッドに必要なパラメータやリクエストボディの構造、そして必要なOAuthスコープを確認することができます。

# Drive APIのfiles.listメソッドのスキーマを確認
gws schema drive.files.list

# Gmail APIのメッセージ取得メソッドのスキーマを確認
gws schema gmail.users.messages.get

例えば、gws schema drive.files.listを実行すると、files.listに必要なスコープの一覧が表示されます。ここでdrive.metadata.readonlyが含まれていれば、ファイル一覧の取得にはdrive（全ファイルの読み書き削除）というフルスコープではなく、drive.metadata.readonlyで十分だと判断することができます。

gws schemaは内部的にGoogle Discovery Serviceから取得したDiscovery Documentを参照しています。

スコープの選択に迷った場合は、まずgws schemaで必要なスコープを確認し、最小権限のスコープを選択するようにしましょう。

AIエージェント連携時のスコープが特に重要

AIエージェントが登場する前は、開発者自身がコードやコマンドを書いて明示的にCLIやAPIを実行させていたため、操作の意図と範囲が明確でした。しかし、AIエージェントの登場により、CLIの実行やAPIアクセスをAIエージェントに委任する場合、設定しているスコープが事実上の「エージェントの行動範囲」を定義することになってしまいます。そのため以下のようなことが起こりえます。

• エージェントはスコープ内で「何でもできる」ため、gmail.modifyを付与すればメールの既読化・ラベル変更・ゴミ箱移動がすべてエージェントの判断に委ねられる
• エージェントの判断ミスにより、承認なしで操作が実行されると、人間のタイプミスとは比較にならないリスクがある

OAuthスコープの範囲やできることをユーザ自身が理解していないと、AIエージェントの異常動作に気づけないため気を付ける必要があります。

認証情報の管理

gws auth loginで認証する

Google Workspace CLIには以下の認証方式が用意されています。

この中で、gws auth loginの利用を推奨します。取得したOAuthトークン（アクセストークン・リフレッシュトークン）はOSのキーリングにAES-256-GCM暗号化で保存されるため、ディスク上に平文の認証情報が残りません。

他の方式は認証情報が環境変数や平文ファイルとして残るため、漏洩リスクが高くなります。

gws auth exportコマンドは、暗号化された認証情報を復号して標準出力に平文で表示します。CI/CD連携やデバッグ用途のコマンドですが、パイプでファイルに保存したり、ターミナルのログに残ったりするリスクがあるため非推奨な認証方式となります。

現在のGoogle Workspace CLI固有の注意点とTips

Pre-1.0であること

Google Workspace CLIはv1.0未満であり、破壊的変更が予告なく行われる可能性があります。
先日初めてインストールした際は、v0.3.3だったのですが、この記事を執筆している現在は、v0.8.0までバージョンが上がっていました。v1.0の公開時期も割とすぐ近くかもしれません。

--dry-runの活用

破壊的操作（ファイル削除、権限変更、メール送信等）の前に--dry-runで実際のリクエスト内容をプレビューすることを強く推奨します。特にAIエージェント経由で操作する場合、--dry-runを挟むことで意図しない操作を事前に検知することができます。

さいごに

Google Workspace CLIを利用する上で最低限気を付けたいポイントを整理しました。

特に重要なポイントは以下の4点です。

• 操作に必要なAPIのみを有効化する: 不必要なAPIを有効化しないことで、トークン漏洩時の被害範囲やAIエージェントの誤操作リスクを限定する
• 必要な操作のみを実現するOAuthスコープを選択する: gws schemaで必要なスコープを確認し、最小権限の原則を徹底する。特にAIエージェント連携時はスコープが「エージェントの行動範囲」を定義するため重要
• 認証情報を適切に管理する: gws auth loginでOSキーリングに暗号化保存し、gws auth exportの出力や漏洩時の対応に注意する
• --dry-runを活用する: 破壊的操作の前に必ずプレビューし、意図しない操作を防止する

Google Workspace CLIはまだv1.0未満のツールですが、AIエージェント時代のWorkspace操作ツールとして大きな可能性を持っています。本記事で紹介した注意点を押さえつつ、安全に活用していただければと思います。

この記事が誰かの助けになれば幸いです。

以上、クラウド事業本部コンサルティング部の渡邉でした！