Skills Atlas · googleworkspace/cli 使用說明書
GitHub 倉庫導覽 · googleworkspace/cli

Repo Deep-Dive — 使用說明書 gws：統一操作 Google Workspace 全部服務的命令列工具，同時為人類與 AI agent 設計。

googleworkspace/cli（命令名 gws）是一個用 Rust 寫成的 Google Workspace 命令列工具 — Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 全部一個 CLI 搞定。它在執行時讀取 Google 的 Discovery Service動態生成整個指令面，所有輸出都是結構化 JSON，並內建 100+ 個 AI agent 技能。注意：這是社群專案，不是 Google 官方支援的產品。

GitHub Stars
26.1k ★
發布首週破萬星、登上 Hacker News 第一，截至 2026 年 5 月約 26k。
Agent 技能
100+
每個支援的 API 一個 SKILL.md，外加高階輔助技能與 50 個精選 recipe。
語言 / 版本
Rust · v0.22.5
幾乎全部以 Rust 寫成，最新版 v0.22.5（2026/03/31）；2026 年 3 月初首次發布。
授權
Apache-2.0
憑證以 AES-256-GCM 加密儲存；社群維護，非官方產品。
01 / 編者手記 FROM THE EDITOR · MAY 2026

gws 以動態生成的 CLI 取代 Workspace API 的手動 SDK 整合。

編者手記 EDITOR'S NOTE

gws 把「Google Workspace API」這件麻煩事壓縮成一個動態生成的 CLI — 你不用查 SDK、不用拼 REST 呼叫，輸出永遠是 JSON。它最聰明的地方是不寫死指令清單：每次跑都讀 Google 的 Discovery Service，Google 一加新端點，它就有。

01

CLI 是給 agent 的最佳工具介面。

對 LLM 來說，一個輸出結構化 JSON、有清楚 exit code、能 dry-run 預覽的 CLI，比一堆零散的 function call 好用得多。gws 就是照這個前提設計的 — 把它丟給 Claude Code、Codex 或 Gemini CLI，配上內建技能，agent 不用任何自訂工具就能管 Workspace。

02

動態指令面，意味著它不會過時。

傳統 SDK／CLI 要追著 API 改版手動補。gws 從 Discovery Service 即時生成指令，所以 Drive、Gmail、Sheets 任何新方法都自動可用，不必等更新。代價是你要會用 --params 帶 JSON 參數 — 換來的是一個永遠最新的工具。

03

它紅得很快，但記得它不是官方產品。

2026 年 3 月初發布，首週破萬星、登上 Hacker News 第一。GitHub repo 在 googleworkspace 帳號下，但 README 明寫「not an officially supported Google product」— 用在正式環境前，把這點和憑證權限範圍一起評估清楚。

02 / 功能總覽 DYNAMIC SURFACE · JSON · 100+ SKILLS · AUTH
01

功能 總覽

六個讓 gws 跟其他 Workspace 工具不一樣的核心設計 — 動態指令面、結構化 JSON、內建技能、輔助指令、驗證方式、錯誤碼與安全防護。

6 Entries
Surface · JSON · Skills · Auth
v0.22.5
01/06
googleworkspace / cli

從 Discovery Service 動態生成整個指令面

Google 加新端點，gws 自動就有 — 不用等更新

gws 在執行時讀取 Google 的 Discovery Service，把 Drive、Gmail、Sheets、Calendar、Docs、Chat、Admin 等服務的所有方法即時反射成指令。語法是 gws <service> <resource> <method> --params '{...}'，例如 gws drive files list --params '{"pageSize": 5}'。沒有「支援哪些指令」的版本落差問題。

✓ 永不過時 Discovery Service --params JSON 全服務覆蓋
Surface 動態生成 Services Drive·Gmail·Sheets… Syntax service resource method
02
googleworkspace / cli · README

全部輸出結構化 JSON

內建自動分頁與 NDJSON 串流

每個回應都是 JSON，方便管線處理與 agent 解析。分頁結果可自動翻頁，並支援以 NDJSON 逐行串流，處理大量資料時不必自己接 pageToken。對寫 shell 腳本或餵給 LLM 都剛好。

JSON 輸出 自動分頁 NDJSON 串流
Output JSON / NDJSON Pagination 自動翻頁
03
googleworkspace / cli · skills/

內建 100+ AI agent 技能

每個 API 一個 SKILL.md，外加 50 個精選 recipe

skills/ 目錄收錄 100+ 個 SKILL.md：每個支援的 API 都有對應技能，再加上處理常見流程的高階輔助技能，以及 50 個替 Gmail、Drive、Docs、Calendar、Sheets 寫好的精選 recipe。完整清單在 docs/skills.md。一鍵安裝：npx skills add https://github.com/googleworkspace/cli，或只挑你要的子技能。把這些丟給 agent，它不用任何自訂工具就能上手。

100+ SKILL.md 50 recipes npx skills add docs/skills.md
Dir skills/ Recipes 50 Doc docs/skills.md
04
googleworkspace / cli · Helper Commands

+ 開頭的輔助指令

把多步 API 操作收成一個動詞

除了動態生成的原始方法，gws 還有一批人性化的輔助指令，用 + 前綴：gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"、gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"、gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"、gws calendar +agenda、gws drive +upload ./report.pdf --name "Q1 Report"、gws workflow +standup-report。

+send +reply +append +agenda +upload
Prefix + Covers gmail·sheets·calendar·drive
05
googleworkspace / cli · Authentication

五種驗證方式 — 桌面到 CI 都能用

互動式 OAuth、Access Token、Service Account、Headless

gws auth setup（需要 gcloud CLI）+ gws auth login 是最快的桌面互動流程；也支援手動 OAuth、用 GOOGLE_WORKSPACE_CLI_TOKEN 帶 access token、用 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 走 service account，以及匯出憑證在無瀏覽器的機器上跑（headless / CI）。憑證一律以 AES-256-GCM 加密儲存。

gws auth setup Access Token Service Account ✓ AES-256-GCM
Quickest auth setup + login CI headless 匯出
06
googleworkspace / cli · Exit Codes

結構化 exit code 與 ModelArmor 防護

0 成功、2 驗證錯、3 參數錯…加上輸出消毒工具

每種錯誤有固定 exit code：0 成功、1 API 錯誤、2 驗證錯誤、3 參數驗證錯誤、4 Discovery 錯誤、5 內部錯誤 — 腳本與 agent 可以據此分支處理。技能集裡還附 ModelArmor 安全消毒工具，用於清理提示詞與回應內容，降低把敏感資料餵進模型的風險。

exit code 0–5 ModelArmor 腳本友善
Exit 0·1·2·3·4·5 Safety ModelArmor
03 / 安裝與設定 npm · cargo · brew · nix · OAUTH · CI
02

安裝與 設定

怎麼裝、怎麼第一次授權、不裝 gcloud 怎麼辦、CI／伺服器怎麼跑、用哪些環境變數，以及怎麼接給 AI agent — 起步前該知道的全部在這裡。

6 Entries
Install · Auth · CI · Agents
起步指南
01/06
googleworkspace / cli — Installation

裝起來 — npm／cargo／brew／nix 四選一

挑你慣用的套件管理器，一行就裝好

npm：npm install -g @googleworkspace/cli；Cargo（從原始碼）：cargo install --git https://github.com/googleworkspace/cli --locked；Homebrew：brew install googleworkspace-cli；Nix（免安裝直接跑）：nix run github:googleworkspace/cli。裝完用 gws --version 確認，目前是 v0.22.5。

✓ 四種安裝路徑 npm / cargo brew / nix 單一二進位
Binary gws Lang Rust Version v0.22.5
02
googleworkspace / cli — Quickstart

三步跑起第一個指令

設定 OAuth → 登入 → 打 API，全程不寫一行樣板

先 gws auth setup 走互動式精靈建立 OAuth 用戶端（會引導你開啟 Google Cloud 專案、啟用 API），接著 gws auth login 在瀏覽器授權，最後 gws drive files list --params '{"pageSize": 5}' 就能拿到結構化 JSON。每個子指令的參數都用 --params 傳 JSON，對應 Discovery 文件裡的欄位。

gws auth setup --params JSON 三步上手
Steps 3 Output JSON
03
googleworkspace / cli — Authentication

不想裝 gcloud？手動帶自己的 OAuth

在 Cloud Console 建一組用戶端，用環境變數餵進來

到 Google Cloud Console 建立 OAuth 2.0 用戶端 ID，然後把 GOOGLE_WORKSPACE_CLI_CLIENT_ID 與 GOOGLE_WORKSPACE_CLI_CLIENT_SECRET 設成環境變數，gws auth login 就會用你自己的憑證走授權流程。憑證會以 AES-256-GCM 加密後存到本機設定目錄，不落明文。

自帶 OAuth client 免 gcloud AES-256-GCM
Method Manual OAuth Storage Encrypted
04
googleworkspace / cli — Service Accounts & CI

Service Account 與無頭環境

CI、伺服器、排程任務都能跑，不需要瀏覽器

把 service account 金鑰路徑放進 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE，或直接用 GOOGLE_WORKSPACE_CLI_TOKEN 傳一個現成 access token 進去，gws 就能在沒有互動登入的環境執行。搭配結構化 exit code，很適合塞進 GitHub Actions 或 cron。

Service Account Headless CI 友善
Env CREDENTIALS_FILE Token TOKEN
05
googleworkspace / cli — Configuration

用環境變數調行為與設定目錄

換設定目錄、開除錯日誌，全靠 env var

GOOGLE_WORKSPACE_CLI_CONFIG_DIR 可以指定設定與加密憑證的存放位置（多帳號／容器化很實用），日誌等級也可透過環境變數調高來除錯。倉庫附了 .env.example，把需要的變數複製過去就能跑。

CONFIG_DIR .env.example 多帳號
Config Env-driven Template .env.example
06
googleworkspace / cli — Agent Integration

接給 Claude Code／Codex／Gemini CLI

倉庫已備好各家 agent 的設定檔，直接認得 gws

倉庫根目錄帶 AGENTS.md、CLAUDE.md、CONTEXT.md 等說明檔，以及 .claude／.gemini／.agent 設定目錄與 gemini-extension.json，讓 Claude Code、Codex、Gemini CLI 等工具一接上就知道怎麼呼叫 gws 與 skills/ 裡的技能。把這個 repo 當成 agent 的 Workspace 能力包就對了。

AGENTS.md CLAUDE.md gemini-extension.json
Configs .claude / .gemini Docs AGENTS.md
04 / 進階用法 --DRY-RUN · --PAGE-ALL · SCHEMA · MODEL ARMOR

六個讓 gws 更好用的旗標與技巧。

以下旗標與用法均記錄於 README。預覽請求、串流分頁、反查 schema、接 Model Armor，是把 gws 安全整合進腳本與 agent 的關鍵細節。

01
README · --dry-run

送出前先預覽 HTTP 請求

任何方法後面加 --dry-run，只組請求不執行

想知道一個指令會打出什麼樣的請求，先 dry-run 一次：gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}' --dry-run。讓 agent 在真正動到使用者資料前先把計畫攤開來給人看，是很實用的安全閘。

--dry-run 安全預演 腳本前置檢查
Flag --dry-run Effect 不發送
02
README · params / json / upload

--params／--json／--upload 各管一塊

查詢參數、請求 body、多段上傳分得很清楚

--params 帶 URL 查詢參數（如 '{"pageSize": 10}'、'{"fileId": "..."}'）；--json 帶請求 body（如 gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'）；--upload 走多段檔案上傳（gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf）。三者對應 Discovery 文件裡的欄位定義。

--params --json --upload
Query --params Body --json
03
README · Pagination

--page-all 把分頁當 NDJSON 串流

一頁一行 JSON，再接 jq 取你要的欄位

gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name' — --page-all 自動翻頁並以 NDJSON 輸出（一頁一行），--page-limit <N> 限制最多翻幾頁（預設 10），--page-delay <MS> 控制頁間延遲（預設 100ms）。處理大量資料時不用自己接 pageToken。

--page-all --page-limit jq 管線
Output NDJSON Default limit 10 頁
04
README · gws schema

gws schema 反查欄位定義

不確定某方法要傳什麼？直接問它的 schema

gws schema drive.files.list 會印出該方法的 request／response schema。對人來說省去翻 REST 文件，對 agent 來說是個自我說明的 introspection 入口 — 先 schema 再組 --params 就不會猜錯欄位。

gws schema introspection 免翻文件
Command gws schema Returns req / resp schema
05
README · Helper Commands

--help 同時列原生方法與 + 輔助指令

還有：Sheets 範圍記得用單引號包

gws gmail --help 會同時顯示 Discovery 生成的方法和 +send／+reply／+triage／+watch 等輔助指令。另外 Sheets 的 Sheet1!A1:C10 範圍含 !，bash 會當成歷史展開 — 一律用單引號把整個 --params JSON 包起來。時間相關的 +agenda／+standup-report 預設用你 Google 帳號的時區，可用 --timezone 覆寫。

gws <svc> --help 單引號包 JSON --timezone
Tip --help 看全部 Sheets single-quote
06
README · Model Armor

--sanitize 接 Model Armor 擋 prompt injection

API 回應先過注入檢查，再交給 agent

gws gmail users messages get --params '...' --sanitize "projects/P/locations/L/templates/T" 會用 Google Cloud Model Armor 範本掃描回應，攔截潛在的 prompt injection。預設範本可放 GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE，模式用 GOOGLE_WORKSPACE_CLI_SANITIZE_MODE（warn 是預設、block 直接擋）。技能集也附了 gws modelarmor +sanitize-prompt／+sanitize-response 輔助指令。

--sanitize SANITIZE_MODE=block +sanitize-response
Flag --sanitize Mode warn / block
05 / 實戰應用 AGENT AUTOMATION · GMAIL · SHEETS · CALENDAR · DRIVE · OPS
03

實戰 應用

六個把 gws 接進真實工作流的場景 — 從 agent 自動化、收件匣分流、試算表記帳，到行事曆 standup、Drive 文件自動化與營運腳本。

6 Entries
Agent · Gmail · Sheets · Ops
實戰場景
01/06
gws · Agent 自動化

讓 AI agent 直接管你的 Workspace

裝上技能，Claude Code／Codex／Gemini CLI 就能讀信、建表、排會議

npx skills add https://github.com/googleworkspace/cli 把 100+ 技能裝進 agent，它就知道怎麼呼叫 gws：抓最近檔案、整理收件匣、把資料寫進 Sheets、建立行事曆事件。每個回應都是 JSON 方便它解析，需要動到使用者資料前先 --dry-run 攤開計畫，再用結構化 exit code 判斷有沒有成功。

✓ 零自訂工具 npx skills add --dry-run 安全閘 JSON 回應
For Claude Code · Codex · Gemini Setup npx skills add Safety --dry-run
02
gws gmail · 收件匣自動化

Gmail 分流、回覆、轉寄一條龍

用 +triage 看未讀摘要，+reply 自動處理 threading

gws gmail +triage 列出未讀寄件人／主旨／日期；gws gmail +reply --message-id MESSAGE_ID --body "Thanks!" 自動接續 thread；gws gmail +forward 轉寄給新收件人；gws gmail +watch 監聽新信並以 NDJSON 串流出來，接 jq 就能做即時分類與通知。

+triage +reply +watch（NDJSON）
Persona 收件匣分流 Stream +watch
03
gws sheets · 資料落點

Google Sheets 當輕量資料庫

cron 寫日誌、自動產報表，全用一行指令

gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95" 每天定時追加一行；gws sheets +read --spreadsheet ID 把資料拉回來算；要新表就 gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'。記得含 ! 的範圍（Sheet1!A1:C10）一律用單引號包住整段 JSON。

+append +read spreadsheets create
Use 日誌 / 報表 Trigger cron
04
gws workflow · standup / 週報

行事曆 standup 與週報自動生成

一個指令把今天的會議與待辦整理成晨會摘要

gws workflow +standup-report 把今天的會議 + 開放任務整理成 standup 摘要；gws workflow +meeting-prep 幫你準備下一場會（議程、與會者、相關文件）；gws workflow +weekly-digest 出本週會議 + 未讀信數；gws calendar +agenda 列近期事件 — 全部自動用你 Google 帳號的時區，需要時用 --timezone 覆寫。

+standup-report +meeting-prep +agenda
Persona 每日 standup TZ 帳號時區
05
gws drive / docs · 文件自動化

Drive 上傳、Docs 追加、Chat 通知一氣呵成

產出檔案、寫進文件、再到頻道宣布

gws drive +upload ./report.pdf --name "Q1 Report" 帶自動 metadata 上傳；要附內容就 gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf；gws docs +write 往 Google 文件追加文字；最後 gws workflow +file-announce 把這份 Drive 檔案在 Chat space 公告出去。整條報表產線不用打開瀏覽器。

drive +upload docs +write +file-announce
Flow 上傳→寫入→通知 Upload --upload
06
gws · 營運與 IT 腳本

把 Workspace 管理塞進 CI 與 cron

service account 跑無頭，exit code 決定流程分支

設好 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 指向 service account 金鑰，gws 就能在 GitHub Actions 或排程任務裡跑；錯誤類型用結構化 exit code（2 驗證、3 參數、1 API…）判斷該重試還是中止。Admin SDK 等服務透過 Discovery 動態取得，Apps Script 專案還能用 gws script +push 一次同步本地檔案。

Service Account exit code 分支 script +push
Persona IT / 營運 Run CI · cron
06 / 社群觀察 VENTUREBEAT · HACKER NEWS · X · DEV · 技能聚合站

發布首月的公開報導與社群資源摘要。

以下為可查證的公開訊號，涵蓋媒體報導、發布者推文、Hacker News 討論串、開發者社群文章與技能聚合站收錄。每張卡片均附原始連結。

01
VentureBeat · 媒體報導

主流科技媒體把它定位成「給 agent 的 Workspace 介面」

標題：Google Workspace CLI 把 Gmail、Docs、Sheets 收進 AI agent 的共用介面

VentureBeat 報導引用 README 自我定位：「one CLI for all of Google Workspace — built for humans and AI agents」，強調結構化 JSON 輸出與 agent 導向工作流，並把它視為 Google 對 agent 生態的正式回應。

媒體報導 agent 生態 2026/03
Source VentureBeat Angle agent 介面
02
X · @addyosmani

由 Google 的 Addy Osmani 親自宣布

「built for humans and agents … 40+ agent skills included」

發布貼文寫道：「Introducing the Google Workspace CLI … built for humans and agents. Google Drive, Gmail, Calendar, and every Workspace API. 40+ agent skills included.」由知名 Google 工程師領銜公開，發布當下就帶起一波討論（之後技能數成長到 100+）。

官方人員發布 Addy Osmani 首發貼文
Source @addyosmani Platform X
03
Hacker News · item 47255881

發布首週衝上 Hacker News 第一

「first week … over 10,000 GitHub stars and hit the top of Hacker News」

多家報導指出 gws 在 2026 年 3 月初發布後的第一週就拿下 1 萬以上 GitHub 星數並登上 Hacker News 首頁第一，HN 討論串聚焦在「動態指令面」「對人與 agent 都好用」這兩點。目前 GitHub 星數已超過 26,000。

HN 第一 首週破萬星 26k+ Stars
Source Hacker News Now 26k+ ★
04
Medium · AI Software Engineer

社群開始整理實測心得與「該知道的招」

「I Tested (New) Google Workspace CLI (And Uncovered The Hacks You Should Know)」

發布後一個月內，Medium 上已有多篇動手實測長文，整理 --dry-run 預演、--page-all NDJSON 串流、+ 輔助指令、Sheets 單引號這類容易被略過的細節，本篇「進階用法」一節即以此為依據。

動手實測 --dry-run / --page-all helper 指令
Source Medium Type 實測長文
05
DEV Community · 開發者視角

開發者社群聚焦零樣板接 Workspace API

入門教學示範三步起手流程，強調每個回應都是 JSON

DEV Community 與 LinkedIn 上的入門教學把重點放在「不用再對著 REST 文件拼 curl」「每個回應都是 JSON」「裝技能後 agent 直接能用」，並逐步示範 gws auth setup → gws auth login → gws drive files list 的起步流程。

開發者社群 零樣板 入門教學
Source DEV.to Focus 零樣板接 API
06
LobeHub · 技能聚合站

被收進 agent 技能市集，列「Top 100+ Skills」

gws 的 skills/ 目錄已被各家聚合站索引、可單獨安裝

LobeHub、Terminal Trove 等聚合站把 googleworkspace/cli 的技能逐一收錄成可搜尋、可單裝的條目（如 gws-auth、gws-drive、gws-gmail），驗證了「npx skills add 挑單一子技能」這個用法在社群裡確實在被採用。

技能聚合 單裝子技能 LobeHub · Terminal Trove
Source LobeHub Listed 100+ skills
07 / 行動計畫 FOUR WAYS TO START — PICK YOUR ROLE

依角色選擇起步路徑

gws 可依用途直接使用，無需先規劃完整導入專案。以下四條路徑分別對應個人使用者、agent 工程師、營運團隊與交付代理商，依角色選擇一條起步即可。

01 · 個人使用者 · POWER USER

從 gws auth setup 開始，在終端機操作 Workspace

npm install -g @googleworkspace/cli → gws auth setup → gws auth login，接著用 gws gmail +triage、gws calendar +agenda、gws workflow +standup-report 取代每天開好幾個分頁。一個下午就上手，憑證以 AES-256-GCM 加密存在本機。

02 · 做 agent 的工程師 · AGENT BUILDER

把 skills/ 裝進 Claude Code／Codex／Gemini CLI

npx skills add https://github.com/googleworkspace/cli 一次裝齊 100+ 技能，或挑 gws-drive、gws-gmail 等子技能。讓 agent 用結構化 JSON + exit code 操作 Workspace，動到使用者資料前一律先 --dry-run，回應再過 Model Armor 的 --sanitize。

03 · 營運／IT 團隊 · OPS & AUTOMATION

用 service account 把 Workspace 管理塞進 CI

設 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE 走無頭驗證，在 GitHub Actions 或 cron 裡跑 gws sheets +append 記日誌、gws drive +upload 歸檔、gws workflow +weekly-digest 發週報，靠 exit code（2 驗證、3 參數、1 API…）決定重試或中止。

04 · 替客戶交付的團隊 · AGENCY

把 gws 當成 agent 交付的標準 Workspace 能力包

客戶需要以 AI 處理信件、排程或報表時，無需自行實作 OAuth 與 API 封裝。在交付的 agent 裡接入 gws 及對應 SKILL.md，再用倉庫附的 AGENTS.md／CLAUDE.md 與 .claude／.gemini 設定檔讓各家工具一接就認得。注意：此工具非 Google 官方支援產品，憑證權限範圍需一併評估。

想把 gws 接進你的 agent 與工作流？

工具是開源的。
把它接成 穩定運轉的自動化，
是 Tenten 在做的事。

Tenten 是 AI-First 設計與技術顧問公司。我們把 Claude、Agent Skills、Agentic Commerce 接進 Headless CMS、Webflow、Shopify Plus 的企業級交付 — 從挑技能、設驗證、寫 CI 部署到正式上線的工作流，讓 gws 這類好工具真正跑在你的產線上。

預約 30 分鐘諮詢 → Tenten Awesome List
Tenten 如何部署這些 Skills
Skills 架構諮詢
依團隊與堆疊選出適配 skills，建立 OpenClaw 路由與 CI/CD 部署流程。
Claude Design System Sprint
兩週固定價格，接上 frontend-design + brand-guidelines 到 production。
Agentic Commerce Build
Shopify Plus / Webflow / Headless 遷移，搭配 Claude + MCP 營運層。