gws

Google Workspace 全 API を 1 本の CLI で。Discovery Document から動的にコマンドを組み立て、JSON 出力と Agent Skills で人間と LLM の両方を想定した設計。

1 — 概要
プロジェクト

gws（googleworkspace/cli）は、Drive・Gmail・Calendar・Sheets など Google Workspace API を統合操作する Rust 製 CLI。静的なサブコマンド一覧を持たず、実行時に Google の Discovery Service を読み取り、API 追加に追従する。

Discovery動的コマンド生成
JSON構造化 stdout
100+Agent Skills
Rustnpm / brew / cargo

npm パッケージ @googleworkspace/cli は GitHub Releases から各 OS 向けバイナリを取得するラッパー。Homebrew・Nix flake・cargo install も利用できる。

非公式プロダクト: Google 公式サポート対象外。v1.0 前のため破壊的変更があり得る。
2 — アーキテクチャ
二段階パース

コマンド木は clap で Discovery Document から都度構築する。成功・失敗・ダウンロードメタデータはすべて JSON で返る。

flowchart LR
  A["argv[1] で service 特定"] --> B["Discovery Document 取得\n（24h キャッシュ）"]
  B --> C["clap::Command 木を構築"]
  C --> D["残り argv を再パース"]
  D --> E["認証 → HTTP 実行"]
  E --> F["JSON stdout"]

リポジトリ構成（要点）

  • crates/google-workspace-cli — CLI 本体（Rust）
  • crates/google-workspace — 共有ライブラリ
  • skills/ — API 別・workflow・recipe・persona の Agent Skills（SKILL.md）
  • npm/ — プラットフォーム別バイナリ取得スクリプト
3 — コマンド構文
基本形 
gws <service> <resource> [sub-resource] <method> [flags]
gws --help
gws <service> --help

主要フラグ

フラグ用途
--params '<JSON>'URL / クエリパラメータ（pageSize、q など）
--json '<JSON>'POST / PUT / PATCH のリクエストボディ
--fields '<MASK>'レスポンスフィールド制限（エージェントのコンテキスト節約に重要）
--page-all自動ページング、NDJSON（1 行 1 JSON）
--dry-run変更系操作のペイロード検証（実行しない）
--upload <PATH>multipart アップロード
--sanitize <TEMPLATE>Model Armor による出力サニタイズ

クイックスタート

gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'
gws schema drive.files.list
エージェント向けルール（CONTEXT.md）: ペイロード不明時は先に gws schema <resource>.<method>。LIST/GET は --fields で巨大 JSON を避ける。変更操作は --dry-run を先に使う。
+ ヘルパーコマンド

Discovery 自動生成に加え、よく使う操作は + 接頭辞の手書きヘルパーとして同梱。Discovery 名と衝突しない。

サービス例説明
gmail+send +triage +watch送信・未読サマリ・NDJSON ストリーム
calendar+insert +agendaイベント作成・予定一覧（アカウント TZ 自動）
sheets+read +append値の読み書き（range はシングルクォート推奨）
drive+uploadメタデータ付きアップロード
workflow+standup-report +meeting-prep複数 API を跨ぐ定型ワークフロー
 
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
gws calendar +agenda --today --timezone America/New_York
gws workflow +standup-report
4 — 認証
方式の選択
状況推奨
gcloud 済みgws auth setup（最速）
GCP プロジェクトのみCloud Console で Desktop OAuth クライアント作成 → gws auth login
既存アクセストークンGOOGLE_WORKSPACE_CLI_TOKEN
サービスアカウント / エクスポート JSONGOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
CI / ヘッドレス対話マシンで gws auth export → 環境変数で渡す

優先順位

優先度ソース設定
1アクセストークンGOOGLE_WORKSPACE_CLI_TOKEN
2資格情報ファイルGOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3暗号化資格情報gws auth login（AES-256-GCM、OS キーリング）
4平文 JSON~/.config/gws/credentials.json
testing mode の OAuth: 未検証アプリは約 25 スコープ上限。recommended プリセット（85+ スコープ）は失敗しうる。gws auth login -s drive,gmail,sheets のように必要サービスだけ選ぶ。テストユーザー登録忘れは「Access blocked」の典型原因。
5 — エージェント向け機能
Agent Skills

skills/ に API 別（gws-drive 等）、workflow（gws-workflow-*）、50 件の recipe、persona スキルが同梱。一覧はリポジトリ内 docs/skills.md。

npx skills add https://github.com/googleworkspace/cli
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive

Gemini CLI OpenClaw npx skills

Gemini CLI 拡張: 先に gws auth setup 後、gemini extensions install https://github.com/googleworkspace/cli。gws-shared スキルは CLI 未インストール時に npm 経由で導入する install ブロックを持つ。

Model Armor

API レスポンスを Google Cloud Model Armor でスキャンし、プロンプトインジェクションをエージェント到達前に検知。

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

デフォルトテンプレート: GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE。モード: GOOGLE_WORKSPACE_CLI_SANITIZE_MODE（warn / block）。

6 — 設定・終了コード
環境変数（抜粋）
変数説明
GOOGLE_WORKSPACE_CLI_CONFIG_DIR設定ディレクトリ（既定 ~/.config/gws）
GOOGLE_WORKSPACE_CLI_CLIENT_ID / _SECRETclient_secret.json の代替
GOOGLE_WORKSPACE_PROJECT_IDクォータ / 課金用 GCP プロジェクト ID
GOOGLE_WORKSPACE_CLI_LOGstderr ログレベル（例: gws=debug）

.env ファイル（dotenvy）にも対応。テンプレートはリポジトリ内 .env.example。

終了コード
コード意味例
0成功—
1API エラーGoogle 4xx / 5xx
2認証エラー資格情報欠落・期限切れ
3検証エラー未知サービス・不正フラグ
4Discovery エラースキーマ取得失敗
5内部エラー予期しない失敗