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

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

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

除了動態生成的原始方法，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。

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 加密儲存。

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

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

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

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

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

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

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

--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 文件裡的欄位定義。

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。

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

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

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 輔助指令。

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

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。

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

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 公告出去。整條報表產線不用打開瀏覽器。

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

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

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

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

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

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

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