@googleworkspace/cli

googleworkspace-cli とは？

googleworkspace/cli（@googleworkspace/cli として公開）は、Google Workspace 用のコマンドラインツールです。Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin などの複数の Workspace API を単一の CLI で操作できます。

コマンドサーフェスは Google の Discovery Service から実行時に動的に構築され、固定のコマンドリストを同梱しません。プロジェクトは「AI agent skills」を含むと記述されており、CLI は構造化 JSON 出力を重視しています。

主な機能

• 複数の Workspace サービス向け単一 CLI: Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin などの Workspace API を1つのインターフェースで操作。
• Discovery Service からの動的コマンド生成: 実行時に Google の Discovery Service を読み込んでコマンドとメソッドを構築するため、新しいエンドポイント/メソッドを静的リストなしで利用可能。
• 構造化 JSON 出力: 自動化や AI エージェント向けに設計。応答を構造化 JSON で返却。
• API メソッドのスキーマ内省: gws schema <...> でメソッドのリクエスト/レスポンススキーマを確認。
• リクエストシミュレーションとページネーション補助: --dry-run でリクエストをプレビュー、--page-all でページネーション結果をストリーミング（jq などのツールへオプション）。
• 複数の認証ワークフロー: ローカル、CI、サーバー向けのセットアップ/ログインをサポート。利用可能な場合 gcloud との統合も。
• バンドルされたエージェントスキル: リポジトリドキュメントで「40+ agent skills」を含むと記載。

googleworkspace-cli の使い方

1. インストール:
   • npm 経由: npm install -g @googleworkspace/cli
   • GitHub Releases からプリビルドバイナリ
   • ソースからビルド: cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux では Homebrew、Nix flake も利用可。)
2. 認証（初回プロジェクトセットアップ後ログイン）:
   • gws auth setup（gcloud のインストールと認証が必要）
   • gws auth login（以降の OAuth ログイン）
   • 手動トークン/コンソールフローでは、ドキュメントに環境変数と手動 OAuth セットアップを記載。
3. リソースに対するコマンド実行。ドキュメントの例:
   • ファイル一覧: gws drive files list --params '{"pageSize": 5}'
   • スプレッドシート作成: gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • Chat メッセージ送信: gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • スキーマ内省: gws schema drive.files.list

ユースケース

• ページネーションと JSON で Drive ワークフロー自動化: Drive リストエンドポイントから大量結果をストリーミングし、下流ツール（例: --page-all 出力を jq と組み合わせ）で処理。
• Gmail/Chat/Calendar リクエストを生 REST 呼び出しなしで送信: CLI のリソース指向コマンドでオブジェクト作成/更新。生成インターフェースに依存。
• 実行前にリクエスト構造を検証: --dry-run で CLI が送信する内容をプレビュー。Sheets、Chat などのペイロード生成に役立つ。
• Workspace API 周りの AI エージェントツール構築: 構造化 JSON 応答と同梱エージェントスキルを利用し、LLM 駆動エージェントがカスタムコードなしでアクションを選択。
• CLI から API メソッドの呼び出し方を発見: メソッド存在は知っているがリクエスト形状不明時、gws schema <method> でリクエスト/レスポンススキーマを確認。

FAQ

• googleworkspace-cli は Google の公式製品ですか？ いいえ。リポジトリに「This is not an officially supported Google product.」と記載。

• 固定のコマンドリストがありますか？ いいえ。ドキュメントによると静的コマンドリストを同梱せず、実行時に Google の Discovery Service を読み込んでコマンドサーフェスを動的に構築。

• インストールと実行に必要なものは？ npm インストールフローでは Node.js 18+ が前提。認証には OAuth 資格情報用の Google Cloud プロジェクト と Workspace アクセス権限付き Google アカウントが必要。

• どの認証セットアップを使いますか？ ドキュメントに複数パス記載:

  • gcloud 支援セットアップ（gws auth setup）: gcloud インストール/認証済み時
  • 自動化不可時の Google Cloud Console 経由手動 OAuth セットアップ
  • 環境変数経由トークン/手動資格情報（ドキュメント参照）

• 開発/テスト時のスコープ関連制限は？ はい。ドキュメントで警告: OAuth アプリが未検証（テストモード）時は同意を ~25 スコープに制限。推奨スコーププリセット（85+ スコープ）は未検証アプリで失敗、特に @gmail.com アカウントで。

代替手段

• curl や HTTP クライアントによる直接 REST API 呼び出し: Workspace エンドポイントを直接呼び出せますが、リクエスト整形、ページネーション、認証の詳細を自分で管理する必要があります。
• 特定の Workspace サービス向け公式 SDK（例: 言語別 Google APIs ライブラリ）: 特定のサービス向けに型付きクライアントメソッドを提供しますが、通常は API ごとに分離されたコードパスで、1 つの動的生成 CLI インターフェースではありません。
• Google APIs 向け他の CLI ツール: 代替 CLI は特定のサービスに特化したり静的コマンドセットを使用したりします。ツールによっては、ここで説明した動的 Discovery Service 駆動のコマンド生成や構造化 JSON + スキーマ内省ワークフローを提供しない場合があります。