@googleworkspace/cli

googleworkspace-cli 是什麼？

googleworkspace/cli（發佈為 @googleworkspace/cli）是 Google Workspace 的命令列工具。它讓您使用單一 CLI 操作多個 Workspace API，例如 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 等。

命令介面是在執行時動態建置，來自 Google 的 Discovery Service，而非固定命令清單。專案也描述為包含「AI agent skills」，CLI 強調結構化 JSON 輸出以利自動化。

主要功能

• 單一 CLI 操作多個 Workspace 服務：提供一個介面互動 Drive、Gmail、Calendar、Sheets、Docs、Chat、Admin 及其他 Workspace API。
• 從 Discovery Service 動態產生命令：命令與方法在執行時由 Google 的 Discovery Service 讀取建置，因此無需靜態命令清單即可取得新端點/方法。
• 結構化 JSON 輸出：設計用於自動化與 AI 代理；回應以結構化 JSON 傳回。
• API 方法結構自省：使用 gws schema <...> 檢查方法的要求/回應結構。
• 請求模擬與分頁輔助：使用 --dry-run 預覽請求，--page-all 串流分頁結果（可選輸出至 jq 等工具）。
• 多種認證流程：支援適合本機、CI 與伺服器的設定/登入流程，並整合可用時的 gcloud。
• 內建代理技能：儲存庫文件指出包含「40+ agent skills」。

如何使用 googleworkspace-cli

1. 安裝 CLI：
   • 透過 npm：npm install -g @googleworkspace/cli
   • 或從 GitHub Releases 使用預建二進位檔
   • 或從來源建置：cargo install --git https://github.com/googleworkspace/cli --locked
   • (macOS/Linux 也可提 Homebrew；Nix flake 可用。)
2. 認證（專案一次性設定，之後登入）：
   • gws auth setup（需安裝並認證 gcloud）
   • gws auth login（後續 OAuth 登入）
   • 手動權杖或主控台流程，文件列出環境變數與手動 OAuth 設定路徑。
3. 對資源執行命令。文件範例流程包括：
   • 列出檔案：gws drive files list --params '{"pageSize": 5}'
   • 建立試算表：gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
   • 傳送 Chat 訊息：gws chat spaces messages create --params '{"parent": "spaces/xyz"}' --json '{"text": "Deploy complete."}'
   • 檢查結構：gws schema drive.files.list

使用情境

• 使用分頁與 JSON 自動化 Drive 流程：從 Drive 列出端點串流大型結果集，並使用下游工具處理（例如結合 --page-all 輸出與 jq）。
• 無需撰寫原始 REST 呼叫即可傳送 Gmail/Chat/Calendar 請求：使用 CLI 的資源導向命令建立或更新物件，依賴產生的介面。
• 執行前驗證請求結構：使用 --dry-run 預覽 CLI 將傳送的內容，有助 Sheets、Chat 等資源的酬載產生。
• 建置 Workspace API 周邊 AI 代理工具：使用結構化 JSON 回應與內建代理技能，讓 LLM 驅動代理決定 Workspace 動作，減少自訂中介。
• 從 CLI 探索 API 方法呼叫方式：當知曉方法存在但不知確切請求形狀時，使用 gws schema <method> 檢查要求/回應結構。

常見問題

• googleworkspace-cli 是 Google 官方產品嗎？ 不是。儲存庫註明：「This is not an officially supported Google product.」

• 它有固定命令清單嗎？ 沒有。文件指出不提供靜態命令清單；它在執行時讀取 Google 的 Discovery Service 並動態建置命令介面。

• 安裝與執行需要什麼？ npm 安裝流程需 Node.js 18+。認證需 Google Cloud 專案 以取得 OAuth 憑證，以及具 Workspace 存取權的 Google 帳戶。

• 該使用哪種認證設定？ 文件描述多種路徑：

  • 有安裝並認證 gcloud 時使用 gcloud 輔助設定（gws auth setup）
  • 無法自動化時透過 Google Cloud 主控台手動 OAuth 設定
  • 透過環境變數的權杖/手動憑證（如文件所述）

• 開發/測試期間有範圍相關限制嗎？ 有。文件警告若 OAuth 應用程式未驗證（測試模式），Google 限制同意範圍至約 25 個，建議範圍預設（85+ 範圍）將對未驗證應用程式失敗—特別是 @gmail.com 帳戶。

替代方案

• 直接使用 curl 或 HTTP 用戶端呼叫 REST API：可直接呼叫 Workspace 端點，但您必須自行處理請求格式、分頁和驗證細節。
• 特定 Workspace 服務的官方 SDK（例如，語言專屬的 Google APIs 程式庫）：提供特定服務的類型化用戶端方法，但通常每個 API 需要獨立的程式碼路徑，而非單一動態產生的 CLI 介面。
• 其他 Google APIs CLI 工具：替代 CLI 可能專注特定服務或使用靜態指令集；視工具而定，可能無法提供此處描述的相同動態 Discovery Service 驅動指令產生，或結構化 JSON + 結構描述自省工作流程。