gws-shared

Google Workspace の CLI gws のスキルを入れるときに、一緒に入れておくものです。Drive・Gmail・カレンダー・スプレッドシートなど、gws のスキルの本文はどれも冒頭で ../gws-shared/SKILL.md を読め、と指示しています。

このスキルは命令の説明書ではなく、その前提をまとめた資料です。認証のやり方、全部の命令に効く旗、命令の組み立て方、安全の決まり、シェルでつまずく点が 1 枚に入っています。

全体の旗

3

命令ごとの旗

7

安全の決まり

4

同梱ファイル（2026-10-23 時点）

0 件

何が書かれているか

• 導入と認証gws を $PATH に置く。gws auth login（ブラウザの OAuth）か、サービスアカウントの鍵
• 全体の旗--format（json・table・yaml・csv）、--dry-run、--sanitize
• 命令の形gws <サービス> <資源> [下の資源] <命令> [旗]
• 命令ごとの旗--params --json -o --upload --page-all --page-limit --page-delay
• 安全の決まり秘密の値を出さない、書き込みと削除の前に確かめる、ほか 2 つ
• シェルの注意と作法zsh の !、JSON の引用符、不具合の報告の仕方

入れておかないとどうなるか

各スキルの本文は、gws-shared が無ければ gws generate-skills で作れ、と書いています。この命令は既定でスキル一式を skills/ に書き出すので、作業中のリポジトリの中で走らせると、スキルのフォルダが数十個まとめて増えます（原本のリポジトリの skills/ には 95 個。2026-10-23 時点）。最初から npx skills add googleworkspace/cli/gws-shared で入れておくほうが手間がありません。

個別のスキルの解説では、gws-drive と gws-gmail-send が、この資料の安全の決まりと OAuth の範囲の話に触れています。

• 特定のサービスを操作したいこの資料には API の命令の一覧が無い。サービスごとのスキルを入れる
• gws を入れられない環境書いてあるのはすべて gws の使い方
• gws 以外の Google の道具を使う旗も認証も gws 専用

これだけを入れても、エージェントは Drive や Gmail の命令を知りません。メールを送るなら gws-gmail-send、予定を作るなら gws-calendar-insert、表に行を足すなら gws-sheets-append のように、用途のスキルと組で使います。

安全の決まりは 4 つ

本文の安全の決まりは次の 4 つです。

• 秘密の値（API の鍵やトークン）をそのまま出さない
• 書き込みと削除の命令は、実行の前に必ず利用者に確かめる
• 壊す操作には --dry-run を使う
• 個人情報や中身の検査に --sanitize を使う

--dry-run と --sanitize が効かない命令がある

+agenda と +triage は読むだけの命令なので、--dry-run が効かなくても書き込みは起きません。ただ、他人が書いた予定の題名やメールの件名が、検査を通らずにエージェントに届きます。この資料の決まりを守らせても、補助の命令ではその守りが働かない場面がある、と知っておいてください。

--sanitize は、Google Cloud の Model Armor のテンプレートの経路（projects/P/locations/L/templates/T の形）を渡して使います。README によると、既定は警告だけで、環境変数 GOOGLE_WORKSPACE_CLI_SANITIZE_MODE を block にすると止めます。Model Armor を使える Google Cloud のプロジェクトが別に要ります。

サービスアカウントの書き方は README と違う

本文は、サービスアカウントを使うなら GOOGLE_APPLICATION_CREDENTIALS に鍵の経路を入れよ、と書いています。README はサービスアカウントに GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE を使う手順を載せています。

コード（auth.rs）が資格情報を探す順は次のとおりです。

1. GOOGLE_WORKSPACE_CLI_TOKEN取得済みのアクセストークン。最優先
2. GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE資格情報のファイル。利用者でもサービスアカウントでもよい
3. 暗号化した資格情報gws auth login で作ったもの
4. 平文の資格情報~/.config/gws/credentials.json
5. GOOGLE_APPLICATION_CREDENTIALS本文が書く方法。ほかに何も無いときだけ使われる

一度でも gws auth login をした機械では、本文の書き方だけではサービスアカウントに切り替わりません。サービスアカウントで動かすときは、README の書き方（GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE）を使うのが確実です。

シェルの引用符

本文のシェルの注意は 2 つです。シートの範囲 Sheet1!A1 の ! は zsh が履歴の展開に使うので、二重引用符で包む。--params と --json の JSON は、中の二重引用符を守るために単引用符で包む。

本文の例は bash や zsh の書き方です。Windows の PowerShell やコマンドプロンプトでは引用符の扱いが違うので、エージェントが例をそのまま写すと JSON が崩れることがあります。

リポジトリに星を付けるよう勧めさせる作法

本文の最後の節は、プロジェクトが役に立ったら利用者にリポジトリへ星を付けるよう勧めよ、と指示しています。不具合や要望は既存の issue を先に検索し、同じものがあればそこに書き足せ、とも書かれています。

作業の途中でエージェントが星を勧めてくるのは、この節によるものです。不要なら、プロンプトで勧めないよう指示してください。

開発中で、Google の公式の製品ではない

README は、v1.0 に向けて互換性の無い変更があり得ると明記し、末尾で Google が公式に支える製品ではないと断っています。本文の版は 0.22.5 です（2026-10-23 時点）。ライセンスは Apache-2.0 です。

これだけ入れれば Gmail や Drive を操作できますか

できません。この資料には、サービスごとの API の命令の一覧も、補助の命令の説明もありません。認証と共通の決まりの資料なので、gws-drive や gws-gmail-send のような用途のスキルと一緒に入れて使います。

入れ忘れるとどうなりますか

各スキルの本文は、gws-shared が見つからなければ gws generate-skills で作れ、と指示しています。この命令は既定でスキル一式を skills/ に書き出すので、思わぬ場所にフォルダが増えることがあります。最初から一緒に入れておくのが手間の少ない方法です。

--dry-run を付ければ何も起きませんか

多くの命令ではそうですが、全部ではありません。+insert や +append は --dry-run で要求を見せるだけになります。一方 +agenda と +triage はこの旗を使わずに API を呼びます。どちらも読むだけの命令なので書き込みは起きませんが、通信はします。

サービスアカウントで動かすには

README の手順どおり、GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE に鍵のファイルの経路を入れます。本文にある GOOGLE_APPLICATION_CREDENTIALS は、gws auth login の資格情報が手元に無いときにしか使われません。