gws

Google Workspace を一つの CLI で — Drive, Gmail, Calendar, Sheets ほか。Discovery 駆動・構造化 JSON・エージェント用スキル付き。

1 — 概要
何か

gws（Google Workspace CLI）は、Drive・Gmail・Calendar・Sheets・Admin など Google Workspace の API を、ひとつの CLI から動的に扱うツール。コマンド一覧を静的に持たず、実行時に Google の Discovery Service を読んでコマンド面を組み立てる。API が増えれば gws も自動で対応する。

Discovery動的コマンド
JSON出力形式
OAuth / SA認証
100+Agent Skills

人間向けには --help・--dry-run・自動ページネーション。AI エージェント向けには構造化 JSON 出力と同梱の Agent Skills で、LLM が Workspace を操作できる。

2 — インストールと認証
インストール

Node.js 18+ でグローバルインストール（プリビルドバイナリ同梱。Rust 不要）:

npm install -g @googleworkspace/cli

バイナリのみが必要な場合は GitHub Releases から取得。ソースからは cargo install --git https://github.com/googleworkspace/cli --locked。Nix では nix run github:googleworkspace/cli。

認証（優先順位）
優先方法設定
1アクセストークンGOOGLE_WORKSPACE_CLI_TOKEN
2認証情報ファイルGOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3暗号化済み認証情報gws auth login で保存
4平文認証情報~/.config/gws/credentials.json

初回は gws auth setup（GCP プロジェクト作成・API 有効化・ログインの案内）。gcloud が無い場合は Google Cloud Console で OAuth クライアントを手動作成し、gws auth login でログイン。サービスアカウントの場合は上記環境変数でキーファイルを指定する。

3 — コマンド構文とフラグ
構文 
gws <service> <resource> [sub-resource] <method> [flags]

例: gws drive files list、gws gmail users messages send。各階層で --help が使える。

主なフラグ
フラグ用途
--params '<JSON>'URL/クエリパラメータ（id, q, pageSize など）
--json '<JSON>'POST/PUT/PATCH のリクエストボディ
--page-all全ページを NDJSON（1 行 1 JSON）で出力
--fields '<MASK>'レスポンスのフィールド制限（コンテキスト節約に重要）
--dry-run変更系の実行前にリクエスト検証のみ
--upload <PATH>マルチパートアップロード用ファイル
--output <PATH>バイナリダウンロード先
--sanitize <TEMPLATE>Google Cloud Model Armor で出力をサニタイズ
4 — 使い方
読み取り（GET/LIST）

--fields で返却フィールドを絞り、トークン消費を抑える:

gws drive files list --params '{"q": "name contains \"Report\"", "pageSize": 10}' --fields "files(id,name,mimeType)"
書き込み（POST/PUT/PATCH）

ボディは --json。本実行前に --dry-run で検証推奨:

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}' --dry-run
ページネーション・スキーマ

大量一覧は --page-all で NDJSON ストリーム。パラメータやボディの形が分からないときは gws schema <service.resource.method> でスキーマを確認する:

gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
gws schema drive.files.list
gws schema sheets.spreadsheets.create
5 — AI エージェント連携
Agent Skills

リポジトリに 100+ の Agent Skills（SKILL.md）が同梱。対応 API ごと＋レシピ（Gmail / Drive / Docs / Calendar / Sheets）。一括または必要なだけ追加:

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

Gemini CLI 拡張では gemini extensions install https://github.com/googleworkspace/cli で gws コマンドとスキルをエージェントに渡せる。認証は端末で一度 gws auth setup すれば拡張から利用される。

エージェント向けルール（CONTEXT.md より）: スキーマが不明なときは先に gws schema <resource>.<method> を実行。一覧系は --params '{"fields": "id,name"}' などでフィールドを絞りコンテキストを保護。変更系は --dry-run で検証してから本実行。
公式