googleworkspace/cli

Google Workspace CLI — one command-line tool for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Dynamically built from Google Discovery Service. Includes AI agent skills.

agent-skillsai-agentautomationclidiscovery-apigemini-cli-extensiongoogle-admingoogle-apigoogle-calendargoogle-chatgoogle-docsgoogle-drivegoogle-sheetsgoogle-workspaceoauth2rust

GAI 中文摘要

gws 是一个基于 Rust 开发的全能型 Google Workspace 命令行工具，旨在为 Drive、Gmail、Calendar、Sheets 等所有 Google 服务提供统一的交互入口。该项目通过动态读取 Google Discovery Service 实现 API 的实时同步，从而彻底消除重复代码并支持最新的 Google 功能扩展。

项目支持超过 40 种内置 AI Agent 技能，能够以结构化 JSON 格式输出操作结果以供程序进一步处理。由于采用动态构建架构，它能够自动捕获并适配 Google Workspace 的任何新增 API 端点或方法。工具支持多种安装方式，包括预编译二进制文件、NPM、Homebrew 以及 Nix 等主流环境。

该工具非常适合需要通过脚本批量管理 Google 工作空间的开发者，以及希望将 Google 服务集成到自动化工作流或 AI 智能体中的技术人员，广泛适用于自动化运维、数据同步及办公流程集成等场景。

⭐

26.7k

Stars

🔱

1.4k

Forks

👁

Watchers

📋

120

Issues

RustApache-2.0创建于 2026/3/2更新于今天

在 GitHub 上查看访问主页

README

由 Gemini 翻译整理

gws

面向人类和 AI 代理的 Google Workspace 全能命令行工具（CLI）。 支持 Drive、Gmail、Calendar 以及所有 Workspace API。无需样板代码，输出结构化 JSON，并内置 40 多种 AI 代理技能。

[!NOTE] 本项目不是 Google 官方支持的产品。

⬇️ 下载适用于您操作系统的最新发布版本

gws 不提供静态的命令列表。它在运行时读取 Google 自身的 Discovery Service，并动态构建完整的命令界面。当 Google Workspace 添加 API 端点或方法时，gws 会自动识别并集成。

[!IMPORTANT] 该项目正处于活跃开发阶段。在我们迈向 v1.0 的过程中，可能会出现破坏性变更。

先决条件

Node.js 18+ — 用于 npm install（或者从 GitHub Releases 下载预构建的二进制文件）
Google Cloud 项目 — 需要 OAuth 凭据。您可以通过 Google Cloud Console、gcloud CLI 或 gws auth setup 命令进行创建。
拥有 Google Workspace 访问权限的 Google 账户

安装

推荐的安装方式是从 GitHub Releases 页面下载适用于您操作系统和架构的预构建二进制文件。解压归档文件并将 gws 二进制文件放入您的 $PATH 中。

为了方便起见，您也可以使用 npm 自动下载 GitHub Releases 中对应的二进制文件：

npm install -g @googleworkspace/cli

或者从源码构建：

cargo install --git https://github.com/googleworkspace/cli --locked

此外，还提供 Nix flake，地址为 github:googleworkspace/cli：

nix run github:googleworkspace/cli

在 macOS 和 Linux 上，您还可以通过 Homebrew 安装：

brew install googleworkspace-cli

快速入门

gws auth setup     # 引导您完成 Google Cloud 项目配置
gws auth login     # 后续 OAuth 登录
gws drive files list --params '{"pageSize": 5}'

为什么选择 gws？

面向人类 — 无需再编写针对 REST 文档的 curl 调用。gws 为每个资源提供 --help 指令、用于预览请求的 --dry-run 选项以及自动分页功能。

面向 AI 代理 — 每个响应都是结构化的 JSON。将其与内置的代理技能配合使用，您的 LLM（大语言模型）无需定制化工具即可管理 Workspace。

# 列出最近的 10 个文件
gws drive files list --params '{"pageSize": 10}'

# 创建电子表格
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# 发送 Chat 消息
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# 查看任何方法的请求/响应模式
gws schema drive.files.list

# 以 NDJSON 格式流式传输分页结果
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

身份验证

该 CLI 支持多种身份验证工作流，因此可以在您的笔记本电脑、CI 环境和服务器上运行。

我应该使用哪种设置？

我拥有……	使用
已安装并登录的 `gcloud`	`gws auth setup` (最快)
有 GCP 项目但没有 `gcloud`	手动 OAuth 设置
现有的 OAuth 访问令牌	`GOOGLE_WORKSPACE_CLI_TOKEN`
现有凭据文件	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`

交互式（本地桌面）

凭据通过 AES-256-GCM 进行静态加密，密钥存储在您的操作系统密钥环中（当 GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file 时存储在 ~/.config/gws/.encryption_key）。

gws auth setup       # 一次性操作：创建云项目，启用 API，完成登录
gws auth login       # 后续作用域选择和登录

gws auth setup 需要 gcloud CLI。如果您没有 gcloud，请使用下方的手动设置。

[!WARNING] 测试模式下的作用域限制： 如果您的 OAuth 应用未经认证（测试模式），Google 会将授权范围限制在约 25 个作用域内。recommended 作用域预设包含 85 个以上的作用域，在未经认证的应用中将会失败（特别是针对 @gmail.com 账户）。请选择个别服务来过滤作用域选择器：
gws auth login -s drive,