Google Workspace CLI (

gws

)

Google Workspace CLI（

gws

）

One CLI for all of Google Workspace — Drive, Gmail, Calendar, Sheets, Docs, Slides, Chat, Tasks, Admin, Meet, Forms, Keep, and every other Workspace API. Built for humans and AI agents. Structured JSON output. 100+ agent skills included.

Note: This is not an officially supported Google product.

Important: This project is under active development. Expect breaking changes as we march toward v1.0.

Repository: https://github.com/googleworkspace/cli

一款适用于所有Google Workspace服务的CLI工具——涵盖Drive、Gmail、Calendar、Sheets、Docs、Slides、Chat、Tasks、Admin、Meet、Forms、Keep以及其他所有Workspace API。为人类用户和AI Agent打造，输出结构化JSON，内置100+ Agent技能。

注意： 这并非Google官方支持的产品。

重要提示： 本项目正处于活跃开发阶段，在推进至v1.0版本过程中可能会出现破坏性变更。

代码仓库： https://github.com/googleworkspace/cli

How It Works

工作原理

gws

does NOT ship a static list of commands. It reads Google's own Discovery Service at runtime and builds its entire command surface dynamically. When Google adds a new API endpoint or method,

gws

picks it up automatically — zero updates needed.

gws

并未内置静态命令列表，它会在运行时读取Google官方的Discovery Service，并动态构建完整的命令体系。当Google新增API端点或方法时，

gws

会自动识别，无需进行任何更新。

Prerequisites

前置要求

Node.js 18+ — for
```
npm install
```
(or download a pre-built binary from GitHub Releases)
A Google Cloud project — required for OAuth credentials. You can create one via the Google Cloud Console, with the
```
gcloud
```
CLI
, or with the
```
gws auth setup
```
command.
A Google account with access to Google Workspace

Node.js 18+ — 用于
```
npm install
```
（也可从GitHub Releases下载预构建二进制文件）
Google Cloud项目 — 用于获取OAuth凭证。可通过Google Cloud Console、
```
gcloud
```
CLI
或
```
gws auth setup
```
命令创建。
拥有Google Workspace访问权限的Google账号

Installation

安装方式

bash

undefined

bash

undefined

Install globally via npm (recommended — bundles native binaries, no Rust needed)

通过npm全局安装（推荐——捆绑原生二进制文件，无需Rust环境）

npm install -g @googleworkspace/cli

Verify installation

验证安装

gws --version


Alternative installation methods:
```bash

gws --version


其他安装方式：
```bash

From GitHub Releases (pre-built binaries)

从GitHub Releases下载预构建二进制文件

Download from: https://github.com/googleworkspace/cli/releases

下载地址：https://github.com/googleworkspace/cli/releases

Build from source (requires Rust toolchain)

从源码构建（需要Rust工具链）

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

Nix flake

Nix flake方式

nix run github:googleworkspace/cli

undefined

nix run github:googleworkspace/cli

undefined

Quick Start

快速开始

bash

gws auth setup     # walks you through Google Cloud project config
gws auth login     # subsequent OAuth login
gws drive files list --params '{"pageSize": 5}'

bash

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

Authentication

认证方式

Which setup should I use?

如何选择认证方式？

I have…	Use
`gcloud` installed and authenticated	`gws auth setup` (fastest — one command)
A GCP project but no `gcloud`	Manual OAuth setup in Cloud Console
An existing OAuth access token	`GOOGLE_WORKSPACE_CLI_TOKEN` env var
Existing credentials JSON (service account or exported)	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` env var

我已拥有…	推荐使用
已安装并完成认证的 `gcloud`	`gws auth setup` （最快——仅需一条命令）
GCP项目但未安装 `gcloud`	在Cloud Console中手动配置OAuth
已获取的OAuth访问令牌	`GOOGLE_WORKSPACE_CLI_TOKEN` 环境变量
已有的凭证JSON文件（服务账号或导出的凭证）	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` 环境变量

Quick Setup (recommended — requires gcloud CLI)

快速配置（推荐——需安装gcloud CLI）

bash

gws auth setup       # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent logins with scope selection

Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring.

bash

gws auth setup       # 一次性操作：创建Cloud项目、启用API、完成登录
gws auth login       # 后续登录时选择权限范围

凭证会通过AES-256-GCM加密存储，密钥保存在系统密钥环中。

Scoped Login (for unverified/testing OAuth apps, limited to ~25 scopes)

限定权限范围登录（针对未验证/测试版OAuth应用，最多支持约25个权限范围）

Warning: Unverified (testing-mode) apps are limited to ~25 OAuth scopes. The
recommended
scope preset includes 85+ scopes and will fail for unverified apps (especially for
@gmail.com
accounts). Choose individual services instead:

bash

undefined

警告： 未验证（测试模式）的应用最多支持约25个OAuth权限范围。
recommended
权限预设包含85+个权限范围，会导致未验证应用登录失败（尤其针对
@gmail.com
账号）。请选择所需的特定服务：

bash

undefined

Select only the services you need to stay under the scope limit

仅选择需要的服务，避免超出权限范围限制

gws auth login -s drive,gmail,sheets gws auth login --scopes drive,gmail,calendar,docs,chat

undefined

gws auth login -s drive,gmail,sheets gws auth login --scopes drive,gmail,calendar,docs,chat

undefined

Multiple Accounts

多账号管理

bash

gws auth login --account work@corp.com
gws auth login --account personal@gmail.com

gws auth list                                    # list registered accounts
gws auth default work@corp.com                   # set the default

gws --account personal@gmail.com drive files list  # one-off override
export GOOGLE_WORKSPACE_CLI_ACCOUNT=personal@gmail.com  # env var override

Credentials are stored per-account as

credentials.<b64-email>.enc

in

~/.config/gws/

, with an

accounts.json

registry tracking defaults.

bash

gws auth login --account work@corp.com
gws auth login --account personal@gmail.com

gws auth list                                    # 列出已注册账号
gws auth default work@corp.com                   # 设置默认账号

gws --account personal@gmail.com drive files list  # 单次覆盖默认账号
export GOOGLE_WORKSPACE_CLI_ACCOUNT=personal@gmail.com  # 通过环境变量覆盖默认账号

凭证按账号存储为

~/.config/gws/

目录下的

credentials.<b64-email>.enc

文件，

accounts.json

文件用于跟踪默认账号。

Manual OAuth Setup (no gcloud)

手动OAuth配置（无需gcloud）

Use this when

gws auth setup

cannot automate project/client creation, or when you want explicit control.

Open Google Cloud Console in the target project:

OAuth consent screen:

https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>

Credentials:

https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>

Configure OAuth branding/audience if prompted — App type: External (testing mode is fine)
Add your account under Test users
Create an OAuth client — Type: Desktop app
Download the client JSON → save to
```
~/.config/gws/client_secret.json
```

Important: You must add yourself as a test user. In the OAuth consent screen, click Test users → Add users and enter your Google account email. Without this, login will fail with a generic "Access blocked" error.

Then run:

bash

gws auth login

当

gws auth setup

无法自动完成项目/客户端创建，或需要完全手动控制时，可使用此方式。

在目标项目中打开Google Cloud Console：

OAuth consent screen：

https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>

凭证页面：

https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>

按提示配置OAuth品牌/受众——应用类型选择External（测试模式即可）
在测试用户中添加你的账号
创建OAuth客户端——类型选择Desktop app
下载客户端JSON文件→保存至
```
~/.config/gws/client_secret.json
```

重要提示： 必须将自己添加为测试用户。在OAuth consent screen页面，点击测试用户 → 添加用户并输入你的Google账号邮箱。否则登录时会显示通用的"Access blocked"错误。

然后运行：

bash

gws auth login

Headless / CI

无头模式 / CI环境

bash

undefined

bash

undefined

On a machine with a browser:

在有浏览器的机器上执行：

gws auth export --unmasked > credentials.json

On the headless machine:

在无头机器上执行：

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json gws drive files list # just works

undefined

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json gws drive files list # 直接运行即可

undefined

Service Account (server-to-server)

服务账号（服务器到服务器）

bash

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

bash

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

For Domain-Wide Delegation:

针对域范围委派：

export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com

undefined

export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com

undefined

Pre-obtained Access Token

预先获取的访问令牌

bash

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

bash

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Browser-Assisted Auth (for AI agents)

浏览器辅助认证（针对AI Agent）

Agents can complete OAuth with browser automation:

Human flow: Run
```
gws auth login
```
, open the printed URL, approve scopes.
Agent-assisted flow: The agent opens the URL, selects the account, handles consent prompts, and returns control once the localhost callback succeeds.

If consent shows "Google hasn't verified this app" (testing mode), click Continue. If scope checkboxes appear, select required scopes (or Select all) before continuing.

Agent可通过浏览器自动化完成OAuth认证：

人工流程： 运行
```
gws auth login
```
，打开打印的URL，同意权限范围。
Agent辅助流程： Agent打开URL，选择账号，处理授权提示，在本地回调成功后恢复控制权。

如果授权页面显示"Google hasn't verified this app"（测试模式），点击继续。如果出现权限范围复选框，选择所需权限（或全选）后继续。

Auth Precedence

认证优先级

Priority	Method	Source
1	Access token	`GOOGLE_WORKSPACE_CLI_TOKEN`
2	Credentials file	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`
3	Per-account encrypted credentials	`gws auth login --account EMAIL`
4	Plaintext credentials	`~/.config/gws/credentials.json`

Account resolution:

--account

flag >

GOOGLE_WORKSPACE_CLI_ACCOUNT

env var > default in

accounts.json

.

All environment variables can also live in a
.env
file in your project root.

优先级	方式	来源
1	访问令牌	`GOOGLE_WORKSPACE_CLI_TOKEN`
2	凭证文件	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`
3	按账号加密存储的凭证	`gws auth login --account EMAIL`
4	明文凭证	`~/.config/gws/credentials.json`

账号解析优先级：

--account

参数 >

GOOGLE_WORKSPACE_CLI_ACCOUNT

环境变量 >

accounts.json

中的默认账号。

所有环境变量也可存储在项目根目录的
.env
文件中。

Command Structure

命令结构

The universal pattern for ALL gws commands:

gws <service> <resource> <method> [--params '{ JSON }'] [--json '{ JSON }'] [flags]

所有gws命令遵循统一格式：

gws <服务名> <资源名> <方法名> [--params '{ JSON }'] [--json '{ JSON }'] [参数]

Global Flags

全局参数

Flag	Description
`--help`	Show help for any service, resource, or method
`--params '{ JSON }'`	URL/query parameters as JSON
`--json '{ JSON }'`	Request body as JSON
`--dry-run`	Preview the HTTP request without executing
`--page-all`	Auto-paginate, one JSON line per page (NDJSON)
`--page-limit <N>`	Max pages to fetch (default: 10)
`--page-delay <MS>`	Delay between pages (default: 100ms)
`--upload <path>`	Multipart file upload
`--account <email>`	Use a specific authenticated account
`--sanitize <template>`	Model Armor response sanitization

参数	描述
`--help`	查看任意服务、资源或方法的帮助信息
`--params '{ JSON }'`	URL/查询参数（JSON格式）
`--json '{ JSON }'`	请求体（JSON格式）
`--dry-run`	预览HTTP请求但不执行
`--page-all`	自动分页，每页输出一行JSON（NDJSON格式）
`--page-limit <N>`	最大获取页数（默认：10）
`--page-delay <MS>`	分页请求间隔（默认：100ms）
`--upload <path>`	多部分文件上传
`--account <email>`	使用指定的已认证账号
`--sanitize <template>`	Model Armor响应内容清理

Introspecting Schemas

查看Schema

bash

undefined

bash

undefined

See the full request/response schema for any method

查看任意方法的完整请求/响应Schema

gws schema drive.files.list gws schema gmail.users.messages.send gws schema calendar.events.insert

undefined

gws schema drive.files.list gws schema gmail.users.messages.send gws schema calendar.events.insert

undefined

Core Services — Commands & Examples

核心服务——命令与示例

Google Drive

bash

undefined

bash

undefined

List files (paginated)

列出文件（分页）

gws drive files list --params '{"pageSize": 10}'

List ALL files (auto-paginate as NDJSON)

列出所有文件（自动分页，输出NDJSON格式）

gws drive files list --params '{"pageSize": 100}' --page-all

Search for files

搜索文件

gws drive files list --params '{"q": "name contains '''report''' and mimeType = '''application/pdf'''", "pageSize": 20}'

gws drive files list --params '{"q": "name contains '\''report'\'' and mimeType = '\''application/pdf'\''", "pageSize": 20}'

Get file metadata

获取文件元数据

gws drive files get --params '{"fileId": "FILE_ID"}'

Upload a file

上传文件

gws drive files create --json '{"name": "report.pdf", "parents": ["FOLDER_ID"]}' --upload ./report.pdf

Create a folder

创建文件夹

gws drive files create --json '{"name": "Project Docs", "mimeType": "application/vnd.google-apps.folder"}'

Move a file to a folder

移动文件至文件夹

gws drive files update --params '{"fileId": "FILE_ID", "addParents": "FOLDER_ID", "removeParents": "OLD_PARENT_ID"}'

Share a file

分享文件

gws drive permissions create --params '{"fileId": "FILE_ID"}' --json '{"role": "writer", "type": "user", "emailAddress": "user@example.com"}'

Download a file (export Google Docs as PDF)

下载文件（将Google Docs导出为PDF）

gws drive files export --params '{"fileId": "FILE_ID", "mimeType": "application/pdf"}'

Delete a file

删除文件

gws drive files delete --params '{"fileId": "FILE_ID"}'

List shared drives

列出共享云端硬盘

gws drive drives list --params '{"pageSize": 10}'

Create a shared drive

创建共享云端硬盘

gws drive drives create --params '{"requestId": "unique-id"}' --json '{"name": "Team Drive"}'

undefined

gws drive drives create --params '{"requestId": "unique-id"}' --json '{"name": "Team Drive"}'

undefined

Gmail

bash

undefined

bash

undefined

List messages in inbox

列出收件箱邮件

gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'

Search messages

搜索邮件

gws gmail users messages list --params '{"userId": "me", "q": "from:boss@company.com is:unread", "maxResults": 20}'

Get a specific message

获取指定邮件

gws gmail users messages get --params '{"userId": "me", "id": "MESSAGE_ID"}'

Send an email

发送邮件

gws gmail users messages send --params '{"userId": "me"}' --json '{ "raw": "<BASE64_ENCODED_RFC2822_MESSAGE>" }'

List labels

列出标签

gws gmail users labels list --params '{"userId": "me"}'

Create a label

创建标签

gws gmail users labels create --params '{"userId": "me"}' --json '{"name": "Important/Projects"}'

Modify message labels

修改邮件标签

gws gmail users messages modify --params '{"userId": "me", "id": "MESSAGE_ID"}' --json '{"addLabelIds": ["LABEL_ID"], "removeLabelIds": ["INBOX"]}'

Trash a message

将邮件移至垃圾箱

gws gmail users messages trash --params '{"userId": "me", "id": "MESSAGE_ID"}'

List drafts

列出草稿

gws gmail users drafts list --params '{"userId": "me"}'

Create a draft

创建草稿

gws gmail users drafts create --params '{"userId": "me"}' --json '{ "message": {"raw": "<BASE64_ENCODED_RFC2822_MESSAGE>"} }'

Set vacation auto-reply

设置假期自动回复

gws gmail users settings updateVacation --params '{"userId": "me"}' --json '{ "enableAutoReply": true, "responseSubject": "Out of Office", "responseBodyPlainText": "I am out of office until March 10.", "restrictToContacts": false, "restrictToDomain": false }'

undefined

gws gmail users settings updateVacation --params '{"userId": "me"}' --json '{ "enableAutoReply": true, "responseSubject": "Out of Office", "responseBodyPlainText": "I am out of office until March 10.", "restrictToContacts": false, "restrictToDomain": false }'

undefined

Google Calendar

bash

undefined

bash

undefined

List upcoming events

列出即将到来的日程

gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-05T00:00:00Z", "maxResults": 10, "singleEvents": true, "orderBy": "startTime"}'

Get a specific event

获取指定日程

gws calendar events get --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'

Create an event

创建日程

gws calendar events insert --params '{"calendarId": "primary"}' --json '{ "summary": "Team Standup", "description": "Daily standup meeting", "start": {"dateTime": "2026-03-06T09:00:00-05:00", "timeZone": "America/New_York"}, "end": {"dateTime": "2026-03-06T09:30:00-05:00", "timeZone": "America/New_York"}, "attendees": [{"email": "alice@example.com"}, {"email": "bob@example.com"}] }'

Update an event

更新日程

gws calendar events update --params '{"calendarId": "primary", "eventId": "EVENT_ID"}' --json '{ "summary": "Updated Standup", "start": {"dateTime": "2026-03-06T10:00:00-05:00"}, "end": {"dateTime": "2026-03-06T10:30:00-05:00"} }'

Delete an event

删除日程

gws calendar events delete --params '{"calendarId": "primary", "eventId": "EVENT_ID"}'

List calendars

列出日历

gws calendar calendarList list

Check free/busy

查看空闲/忙碌状态

gws calendar freebusy query --json '{ "timeMin": "2026-03-06T08:00:00Z", "timeMax": "2026-03-06T18:00:00Z", "items": [{"id": "alice@example.com"}, {"id": "bob@example.com"}] }'

Create a recurring event

创建重复日程

gws calendar events insert --params '{"calendarId": "primary"}' --json '{ "summary": "Weekly Review", "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=FR"], "start": {"dateTime": "2026-03-06T16:00:00-05:00", "timeZone": "America/New_York"}, "end": {"dateTime": "2026-03-06T17:00:00-05:00", "timeZone": "America/New_York"} }'

undefined

gws calendar events insert --params '{"calendarId": "primary"}' --json '{ "summary": "Weekly Review", "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=FR"], "start": {"dateTime": "2026-03-06T16:00:00-05:00", "timeZone": "America/New_York"}, "end": {"dateTime": "2026-03-06T17:00:00-05:00", "timeZone": "America/New_York"} }'

undefined

Google Sheets

Important: Sheets ranges use

which bash interprets as history expansion. Always wrap values in single quotes.

bash

undefined

重要提示： Sheets范围使用

，而bash会将其解析为历史扩展。请始终用单引号包裹对应值。

bash

undefined

Create a spreadsheet

创建电子表格

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

Read cells

读取单元格内容

gws sheets spreadsheets values get --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

Write cells

写入单元格内容

gws sheets spreadsheets values update --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' --json '{"values": [["Name", "Score"], ["Alice", 95], ["Bob", 87]]}'

Append rows

追加行

gws sheets spreadsheets values append --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' --json '{"values": [["Charlie", 92]]}'

Get spreadsheet metadata

获取电子表格元数据

gws sheets spreadsheets get --params '{"spreadsheetId": "SPREADSHEET_ID"}'

Clear a range

清空指定范围内容

gws sheets spreadsheets values clear --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'

Batch update (add sheet, format cells, etc.)

批量更新（添加工作表、格式化单元格等）

gws sheets spreadsheets batchUpdate --params '{"spreadsheetId": "SPREADSHEET_ID"}' --json '{ "requests": [ {"addSheet": {"properties": {"title": "March Data"}}}, {"repeatCell": { "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1}, "cell": {"userEnteredFormat": {"textFormat": {"bold": true}}}, "fields": "userEnteredFormat.textFormat.bold" }} ] }'

undefined

gws sheets spreadsheets batchUpdate --params '{"spreadsheetId": "SPREADSHEET_ID"}' --json '{ "requests": [ {"addSheet": {"properties": {"title": "March Data"}}}, {"repeatCell": { "range": {"sheetId": 0, "startRowIndex": 0, "endRowIndex": 1}, "cell": {"userEnteredFormat": {"textFormat": {"bold": true}}}, "fields": "userEnteredFormat.textFormat.bold" }} ] }'

undefined

Google Docs

bash

undefined

bash

undefined

Create a document

创建文档

gws docs documents create --json '{"title": "Meeting Notes"}'

Get document content

获取文档内容

gws docs documents get --params '{"documentId": "DOC_ID"}'

Update document (insert text)

更新文档（插入文本）

gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json '{ "requests": [ {"insertText": {"location": {"index": 1}, "text": "Hello, World!\n"}} ] }'

undefined

gws docs documents batchUpdate --params '{"documentId": "DOC_ID"}' --json '{ "requests": [ {"insertText": {"location": {"index": 1}, "text": "Hello, World!
"}} ] }'

undefined

Google Slides

bash

undefined

bash

undefined

Create a presentation

创建演示文稿

gws slides presentations create --json '{"title": "Q1 Review"}'

Get presentation

获取演示文稿

gws slides presentations get --params '{"presentationId": "PRES_ID"}'

Add a slide

添加幻灯片

gws slides presentations batchUpdate --params '{"presentationId": "PRES_ID"}' --json '{ "requests": [ {"createSlide": {"slideLayoutReference": {"predefinedLayout": "TITLE_AND_BODY"}}} ] }'

undefined

gws slides presentations batchUpdate --params '{"presentationId": "PRES_ID"}' --json '{ "requests": [ {"createSlide": {"slideLayoutReference": {"predefinedLayout": "TITLE_AND_BODY"}}} ] }'

undefined

Google Chat

bash

undefined

bash

undefined

List spaces

列出空间

gws chat spaces list

Send a message to a space

向空间发送消息

gws chat spaces messages create --params '{"parent": "spaces/SPACE_ID"}' --json '{"text": "Deploy complete."}'

Get a message

获取消息

gws chat spaces messages get --params '{"name": "spaces/SPACE_ID/messages/MSG_ID"}'

List messages in a space

列出空间内的消息

gws chat spaces messages list --params '{"parent": "spaces/SPACE_ID", "pageSize": 25}'

Create a space

创建空间

gws chat spaces create --json '{"displayName": "Project Alpha", "spaceType": "SPACE"}'

undefined

gws chat spaces create --json '{"displayName": "Project Alpha", "spaceType": "SPACE"}'

undefined

Google Tasks

bash

undefined

bash

undefined

List task lists

列出任务列表

gws tasks tasklists list

Create a task list

创建任务列表

gws tasks tasklists insert --json '{"title": "Sprint 42"}'

List tasks in a list

列出任务列表中的任务

gws tasks tasks list --params '{"tasklist": "TASKLIST_ID"}'

Create a task

创建任务

gws tasks tasks insert --params '{"tasklist": "TASKLIST_ID"}' --json '{"title": "Review PR #123", "due": "2026-03-07T00:00:00Z"}'

Complete a task

标记任务为完成

gws tasks tasks update --params '{"tasklist": "TASKLIST_ID", "task": "TASK_ID"}' --json '{"status": "completed"}'

undefined

gws tasks tasks update --params '{"tasklist": "TASKLIST_ID", "task": "TASK_ID"}' --json '{"status": "completed"}'

undefined

Google Meet

bash

undefined

bash

undefined

Create a meeting space

创建会议空间

gws meet spaces create --json '{}'

Get meeting space info

获取会议空间信息

gws meet spaces get --params '{"name": "spaces/SPACE_ID"}'

undefined

gws meet spaces get --params '{"name": "spaces/SPACE_ID"}'

undefined

Google Forms

bash

undefined

bash

undefined

Create a form

创建表单

gws forms forms create --json '{"info": {"title": "Feedback Survey"}}'

Get form

获取表单

gws forms forms get --params '{"formId": "FORM_ID"}'

List responses

列出表单响应

gws forms forms responses list --params '{"formId": "FORM_ID"}'

undefined

gws forms forms responses list --params '{"formId": "FORM_ID"}'

undefined

Google Admin (Directory)

Google Admin（目录）

bash

undefined

bash

undefined

List users

列出用户

gws admin users list --params '{"domain": "example.com", "maxResults": 100}'

Get a user

获取用户信息

gws admin users get --params '{"userKey": "user@example.com"}'

Create a user

创建用户

gws admin users insert --json '{ "primaryEmail": "newuser@example.com", "name": {"givenName": "Jane", "familyName": "Doe"}, "password": "TempP@ssw0rd!" }'

List groups

列出群组

gws admin groups list --params '{"domain": "example.com"}'

Add member to group

添加成员至群组

gws admin members insert --params '{"groupKey": "group@example.com"}' --json '{"email": "user@example.com", "role": "MEMBER"}'

undefined

gws admin members insert --params '{"groupKey": "group@example.com"}' --json '{"email": "user@example.com", "role": "MEMBER"}'

undefined

Google Keep

bash

undefined

bash

undefined

List notes

列出笔记

gws keep notes list

Get a note

获取笔记

gws keep notes get --params '{"name": "notes/NOTE_ID"}'

undefined

gws keep notes get --params '{"name": "notes/NOTE_ID"}'

undefined

Google People (Contacts & Profiles)

Google People（联系人和个人资料）

bash

undefined

bash

undefined

List contacts

列出联系人

gws people people connections list --params '{"resourceName": "people/me", "personFields": "names,emailAddresses,phoneNumbers", "pageSize": 50}'

Get a specific contact

获取指定联系人

gws people people get --params '{"resourceName": "people/PERSON_ID", "personFields": "names,emailAddresses,organizations"}'

Search contacts

搜索联系人

gws people people searchContacts --params '{"query": "Alice", "readMask": "names,emailAddresses"}'

Create a contact

创建联系人

gws people people createContact --json '{ "names": [{"givenName": "Jane", "familyName": "Smith"}], "emailAddresses": [{"value": "jane@example.com"}], "phoneNumbers": [{"value": "+1-555-0100"}] }'

List directory (domain contacts)

列出目录联系人（域内联系人）

gws people people listDirectoryPeople --params '{"readMask": "names,emailAddresses", "sources": ["DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE"], "pageSize": 100}'

undefined

gws people people listDirectoryPeople --params '{"readMask": "names,emailAddresses", "sources": ["DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE"], "pageSize": 100}'

undefined

Google Workspace Events

bash

undefined

bash

undefined

Create a subscription to watch for changes

创建订阅以监控变更

gws events subscriptions create --json '{ "targetResource": "//calendar.googleapis.com/calendars/primary", "eventTypes": ["google.workspace.calendar.event.v1.created"], "notificationEndpoint": {"pubsubTopic": "projects/PROJECT/topics/TOPIC"}, "payloadOptions": {"includeResource": true} }'

List subscriptions

列出订阅

gws events subscriptions list

Delete a subscription

删除订阅

gws events subscriptions delete --params '{"name": "subscriptions/SUB_ID"}'

undefined

gws events subscriptions delete --params '{"name": "subscriptions/SUB_ID"}'

undefined

Google Vault (eDiscovery)

Google Vault（电子取证）

bash

undefined

bash

undefined

List matters

列出事项

gws vault matters list

Create a matter

创建事项

gws vault matters create --json '{"name": "Investigation Q1", "description": "Q1 compliance audit"}'

Create a hold

创建保留规则

gws vault matters holds create --params '{"matterId": "MATTER_ID"}' --json '{ "name": "Email Hold", "corpus": "MAIL", "accounts": [{"accountId": "user@example.com"}] }'

undefined

gws vault matters holds create --params '{"matterId": "MATTER_ID"}' --json '{ "name": "Email Hold", "corpus": "MAIL", "accounts": [{"accountId": "user@example.com"}] }'

undefined

Google Classroom

bash

undefined

bash

undefined

List courses

列出课程

gws classroom courses list

Create a course

创建课程

gws classroom courses create --json '{"name": "CS101", "section": "Fall 2026", "ownerId": "me"}'

List students in a course

列出课程中的学生

gws classroom courses students list --params '{"courseId": "COURSE_ID"}'

Create coursework

创建课程作业

gws classroom courses courseWork create --params '{"courseId": "COURSE_ID"}' --json '{ "title": "Assignment 1", "workType": "ASSIGNMENT", "dueDate": {"year": 2026, "month": 3, "day": 15} }'

undefined

gws classroom courses courseWork create --params '{"courseId": "COURSE_ID"}' --json '{ "title": "Assignment 1", "workType": "ASSIGNMENT", "dueDate": {"year": 2026, "month": 3, "day": 15} }'

undefined

Admin Reports (Audit Logs)

Admin Reports（审计日志）

bash

undefined

bash

undefined

List admin activities

列出管理员活动

gws admin-reports activities list --params '{"userKey": "all", "applicationName": "admin", "maxResults": 50}'

List login activities

列出登录活动

gws admin-reports activities list --params '{"userKey": "all", "applicationName": "login", "maxResults": 50}'

List Drive audit logs

列出Drive审计日志

gws admin-reports activities list --params '{"userKey": "all", "applicationName": "drive", "maxResults": 50}'

undefined

gws admin-reports activities list --params '{"userKey": "all", "applicationName": "drive", "maxResults": 50}'

undefined

Alert Center (Security Alerts)

Alert Center（安全警报）

bash

undefined

bash

undefined

List alerts

列出警报

gws alertcenter alerts list

Get alert details

获取警报详情

gws alertcenter alerts get --params '{"alertId": "ALERT_ID"}'

undefined

gws alertcenter alerts get --params '{"alertId": "ALERT_ID"}'

undefined

Cloud Identity

bash

undefined

bash

undefined

List groups

列出群组

gws cloudidentity groups list --params '{"parent": "customers/CUSTOMER_ID"}'

Search groups

搜索群组

gws cloudidentity groups search --params '{"query": "parent == "customers/CUSTOMER_ID""}'

gws cloudidentity groups search --params '{"query": "parent == \"customers/CUSTOMER_ID\""}'

List memberships

列出群组成员

gws cloudidentity groups memberships list --params '{"parent": "groups/GROUP_ID"}'

undefined

gws cloudidentity groups memberships list --params '{"parent": "groups/GROUP_ID"}'

undefined

Groups Settings

bash

undefined

bash

undefined

Get group settings

获取群组设置

gws groupssettings groups get --params '{"groupUniqueId": "group@example.com"}'

Update group settings

更新群组设置

gws groupssettings groups update --params '{"groupUniqueId": "group@example.com"}' --json '{ "whoCanPostMessage": "ALL_MEMBERS_CAN_POST", "messageModerationLevel": "MODERATE_NONE" }'

undefined

gws groupssettings groups update --params '{"groupUniqueId": "group@example.com"}' --json '{ "whoCanPostMessage": "ALL_MEMBERS_CAN_POST", "messageModerationLevel": "MODERATE_NONE" }'

undefined

Licensing

bash

undefined

bash

undefined

List license assignments

列出许可证分配情况

gws licensing licenseAssignments listForProduct --params '{"productId": "Google-Apps", "customerId": "CUSTOMER_ID"}'

Assign a license

分配许可证

gws licensing licenseAssignments insert --params '{"productId": "Google-Apps", "skuId": "SKU_ID"}' --json '{"userId": "user@example.com"}'

undefined

gws licensing licenseAssignments insert --params '{"productId": "Google-Apps", "skuId": "SKU_ID"}' --json '{"userId": "user@example.com"}'

undefined

Reseller

bash

undefined

bash

undefined

List subscriptions

列出订阅

gws reseller subscriptions list --params '{"customerId": "CUSTOMER_ID"}'

Get a subscription

获取订阅

gws reseller subscriptions get --params '{"customerId": "CUSTOMER_ID", "subscriptionId": "SUB_ID"}'

undefined

gws reseller subscriptions get --params '{"customerId": "CUSTOMER_ID", "subscriptionId": "SUB_ID"}'

undefined

Apps Script

bash

undefined

bash

undefined

List projects

列出项目

gws apps-script projects list

Get project content

获取项目内容

gws apps-script projects getContent --params '{"scriptId": "SCRIPT_ID"}'

Deploy a project

部署项目

gws apps-script projects deployments create --params '{"scriptId": "SCRIPT_ID"}' --json '{"versionNumber": 1}'

Run a function

运行函数

gws apps-script scripts run --params '{"scriptId": "SCRIPT_ID"}' --json '{"function": "myFunction", "parameters": []}'

undefined

gws apps-script scripts run --params '{"scriptId": "SCRIPT_ID"}' --json '{"function": "myFunction", "parameters": []}'

undefined

Workflow Helpers (Shortcut Commands)

工作流助手（快捷命令）

gws

ships higher-level helper commands for the most common multi-step operations:

bash

undefined

gws

内置了针对常见多步骤操作的高阶快捷命令：

bash

undefined

--- Drive ---

Upload a file to Drive with automatic metadata

上传文件至Drive并自动添加元数据

gws drive-upload ./report.pdf

--- Sheets ---

Append a row to a sheet

向表格追加行

gws sheets-append --spreadsheet-id ID --range 'Sheet1!A1' --values '[["Name", "Score"]]'

Read sheet values

读取表格内容

gws sheets-read --spreadsheet-id ID --range 'Sheet1!A1:C10'

--- Gmail ---

Send an email (simplified)

简化版发送邮件

gws gmail-send --to user@example.com --subject "Hello" --body "Hi there"

Triage inbox — show unread summary (sender, subject, date)

收件箱分类——显示未读邮件摘要（发件人、主题、日期）

gws gmail-triage

Watch for new emails and stream them as NDJSON

监控新邮件并以NDJSON格式输出

gws gmail-watch

--- Calendar ---

Show upcoming calendar agenda across all calendars

显示所有日历中即将到来的日程

gws calendar-agenda

Insert a calendar event quickly

快速创建日历日程

gws calendar-insert --summary "Lunch" --start "2026-03-06T12:00:00" --end "2026-03-06T13:00:00"

--- Docs ---

Append text to a Google Doc

向Google Doc追加文本

gws docs-write --document-id DOC_ID --text "New paragraph here"

--- Chat ---

Send a Chat message to a space

向Chat空间发送消息

gws chat-send --space "spaces/SPACE_ID" --text "Hello team!"

--- Apps Script ---

Upload local files to an Apps Script project

将本地文件上传至Apps Script项目

gws apps-script-push --script-id SCRIPT_ID --source ./src

--- Workspace Events ---

Subscribe to Workspace events and stream them as NDJSON

订阅Workspace事件并以NDJSON格式输出

gws events-subscribe --target "//calendar.googleapis.com/calendars/primary" --event-types "google.workspace.calendar.event.v1.created"

Renew/reactivate Workspace Events subscriptions

续订/重新激活Workspace Events订阅

gws events-renew --subscription-id SUB_ID

--- Model Armor ---

Sanitize a user prompt through a Model Armor template

通过Model Armor模板清理用户提示

gws modelarmor-sanitize-prompt --template "projects/P/locations/L/templates/T" --text "user input here"

Sanitize a model response through a Model Armor template

通过Model Armor模板清理模型响应

gws modelarmor-sanitize-response --template "projects/P/locations/L/templates/T" --text "model output here"

Create a new Model Armor template

创建新的Model Armor模板

gws modelarmor-create-template --project PROJECT --location LOCATION --template-id my-template

--- Cross-service Workflows ---

--- 跨服务工作流 ---

Today's standup report (meetings + open tasks)

今日站会报告（会议+未完成任务）

gws workflow-standup-report

Meeting prep (agenda, attendees, linked docs)

会议准备（议程、参会人、关联文档）

gws workflow-meeting-prep

Convert email to task

将邮件转换为任务

gws workflow-email-to-task --message-id MSG_ID

Weekly digest (meetings + unread count)

每周摘要（会议+未读邮件数）

gws workflow-weekly-digest

Announce a Drive file in a Chat space

在Chat空间中分享Drive文件

gws workflow-file-announce --file-id FILE_ID --space "spaces/SPACE_ID"

undefined

gws workflow-file-announce --file-id FILE_ID --space "spaces/SPACE_ID"

undefined

Installing gws Skills Into Your Agent Project

将gws技能安装至你的Agent项目

The gws repo ships 100+ SKILL.md files you can install directly into your agent's skills directory:

bash

undefined

gws仓库提供了100+ SKILL.md文件，可直接安装至Agent的技能目录：

bash

undefined

Install ALL gws skills at once

一次性安装所有gws技能

npx skills add https://github.com/googleworkspace/cli

Or pick only what you need

或仅安装所需技能

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-calendar npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-sheets npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-docs npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat


<details>
<summary>OpenClaw setup</summary>

```bash

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-calendar npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-sheets npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-docs npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-chat


<details>
<summary>OpenClaw配置</summary>

```bash

Symlink all skills (stays in sync with repo)

符号链接所有技能（与仓库保持同步）

ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

Or copy specific skills

或复制指定技能

cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/


The `gws-shared` skill includes an `install` block so OpenClaw auto-installs the CLI via `npm` if `gws` isn't on PATH.

</details>

This places SKILL.md files into your project's `.github/skills/` (Copilot), `.claude/skills/` (Claude Code), or equivalent directory, giving your agent deep per-service knowledge.

cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/


`gws-shared`技能包含`install`块，因此如果`gws`未在PATH中，OpenClaw会自动通过`npm`安装CLI。

</details>

此操作会将SKILL.md文件添加至项目的`.github/skills/`（Copilot）、`.claude/skills/`（Claude Code）或对应目录，让Agent具备各服务的深度操作能力。

Personas (Role-Based Skill Bundles)

角色模板（基于角色的技能包）

The gws repo includes 10 pre-built persona bundles that combine multiple services for common roles:

Persona	Description	Services Used
`persona-exec-assistant`	Manage an executive's schedule, inbox, and communications	Calendar, Gmail, Chat, Tasks
`persona-project-manager`	Coordinate projects — track tasks, schedule meetings, share docs	Tasks, Calendar, Drive, Chat
`persona-hr-coordinator`	Handle HR workflows — onboarding, announcements, employee comms	Admin, Gmail, Calendar, Docs
`persona-sales-ops`	Manage sales workflows — track deals, schedule calls, client comms	Sheets, Gmail, Calendar, Chat
`persona-it-admin`	Administer IT — manage users, monitor security, configure Workspace	Admin, Alert Center, Cloud Identity
`persona-content-creator`	Create, organize, and distribute content across Workspace	Docs, Slides, Drive, Gmail
`persona-customer-support`	Manage customer support — track tickets, respond, escalate issues	Gmail, Sheets, Chat, Tasks
`persona-event-coordinator`	Plan and manage events — scheduling, invitations, and logistics	Calendar, Gmail, Drive, Chat
`persona-team-lead`	Lead a team — run standups, coordinate tasks, communicate	Calendar, Tasks, Chat, Gmail
`persona-researcher`	Organize research — manage references, notes, collaboration	Drive, Docs, Keep, Sheets

Install a persona:

bash

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/persona-exec-assistant
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/persona-it-admin

gws仓库包含10个预构建的角色模板，整合了多个服务以适配常见角色：

角色模板	描述	使用的服务
`persona-exec-assistant`	管理高管的日程、收件箱和沟通事务	Calendar、Gmail、Chat、Tasks
`persona-project-manager`	协调项目——跟踪任务、安排会议、分享文档	Tasks、Calendar、Drive、Chat
`persona-hr-coordinator`	处理HR工作流——入职、公告、员工沟通	Admin、Gmail、Calendar、Docs
`persona-sales-ops`	管理销售工作流——跟踪客户、安排通话、客户沟通	Sheets、Gmail、Calendar、Chat
`persona-it-admin`	管理IT事务——用户管理、安全监控、Workspace配置	Admin、Alert Center、Cloud Identity
`persona-content-creator`	创建、整理和分发Workspace内容	Docs、Slides、Drive、Gmail
`persona-customer-support`	管理客户支持——跟踪工单、响应、升级问题	Gmail、Sheets、Chat、Tasks
`persona-event-coordinator`	策划和管理活动——日程安排、邀请、后勤	Calendar、Gmail、Drive、Chat
`persona-team-lead`	领导团队——主持站会、协调任务、沟通	Calendar、Tasks、Chat、Gmail
`persona-researcher`	整理研究资料——管理参考资料、笔记、协作	Drive、Docs、Keep、Sheets

安装角色模板：

bash

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/persona-exec-assistant
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/persona-it-admin

Recipes (Multi-Step Task Sequences)

工作流模板（多步骤任务序列）

The gws repo ships 50 curated recipes — multi-step task sequences with real commands. Key recipes:

Recipe	What It Does
`recipe-audit-external-sharing`	Find and review Drive files shared outside the org
`recipe-label-and-archive-emails`	Apply Gmail labels to matching messages and archive them
`recipe-send-personalized-emails`	Read from Sheets, send personalized Gmail to each row
`recipe-draft-email-from-doc`	Read a Google Doc and use it as Gmail body
`recipe-organize-drive-folder`	Create folder structure and move files into place
`recipe-share-folder-with-team`	Share a Drive folder with collaborators
`recipe-email-drive-link`	Share a file and email the link
`recipe-create-doc-from-template`	Copy a Docs template, fill content, share
`recipe-create-expense-tracker`	Set up Sheets for expense tracking
`recipe-block-focus-time`	Create recurring focus time on Calendar
`recipe-reschedule-meeting`	Move event and notify attendees
`recipe-search-and-export-emails`	Find matching Gmail messages and export
`recipe-create-gmail-filter`	Auto-label/star incoming messages
`recipe-cancel-and-notify`	Delete event and send cancellation email
`recipe-find-free-time`	Query free/busy for multiple users
`recipe-bulk-download-folder`	Download all files from a Drive folder
`recipe-find-large-files`	Identify large Drive files consuming storage
`recipe-create-shared-drive`	Create Shared Drive and add members
`recipe-transfer-file-ownership`	Transfer Drive file ownership between users
`recipe-post-mortem-setup`	Create Doc, schedule Calendar review, notify via Chat
`recipe-save-email-attachments`	Save Gmail attachments to Drive
`recipe-send-team-announcement`	Announce via Gmail and Chat simultaneously
`recipe-create-feedback-form`	Create Form and share via Gmail
`recipe-sync-contacts-to-sheet`	Export contacts directory to Sheets
`recipe-create-events-from-sheet`	Read Sheets data and create Calendar events
`recipe-generate-report-from-sheet`	Read Sheets data and create Docs report
`recipe-save-email-to-doc`	Archive Gmail message body into a Doc
`recipe-batch-reply-to-emails`	Find matching emails and send standard reply
`recipe-batch-rename-files`	Rename Drive files to consistent naming
`recipe-create-vacation-responder`	Enable Gmail out-of-office auto-reply
`recipe-triage-security-alerts`	Review Workspace security alerts
`recipe-deploy-apps-script`	Push local files to Apps Script project
`recipe-create-meet-space`	Create Meet space and share join link
`recipe-create-presentation`	Create Slides presentation with initial slides
`recipe-create-classroom-course`	Create Classroom course and invite students

Install recipes:

bash

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/recipe-send-personalized-emails
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/recipe-audit-external-sharing

Full list: https://github.com/googleworkspace/cli/blob/main/docs/skills.md

gws仓库提供了50个精心设计的工作流模板——包含实际命令的多步骤任务序列。核心模板：

模板	功能
`recipe-audit-external-sharing`	查找并审核Drive中分享至外部的文件
`recipe-label-and-archive-emails`	为匹配的邮件添加Gmail标签并归档
`recipe-send-personalized-emails`	读取Sheets数据，向每行记录发送个性化Gmail邮件
`recipe-draft-email-from-doc`	读取Google Doc内容并作为Gmail邮件正文
`recipe-organize-drive-folder`	创建文件夹结构并移动文件至对应位置
`recipe-share-folder-with-team`	与团队成员分享Drive文件夹
`recipe-email-drive-link`	分享文件并通过邮件发送链接
`recipe-create-doc-from-template`	复制Docs模板、填充内容并分享
`recipe-create-expense-tracker`	设置Sheets用于费用跟踪
`recipe-block-focus-time`	在Calendar中创建重复的专注时段
`recipe-reschedule-meeting`	调整会议时间并通知参会人
`recipe-search-and-export-emails`	查找匹配的Gmail邮件并导出
`recipe-create-gmail-filter`	自动为收到的邮件添加标签/星标
`recipe-cancel-and-notify`	删除日程并发送取消通知邮件
`recipe-find-free-time`	查询多个用户的空闲/忙碌状态
`recipe-bulk-download-folder`	下载Drive文件夹中的所有文件
`recipe-find-large-files`	识别占用存储空间的大文件
`recipe-create-shared-drive`	创建共享云端硬盘并添加成员
`recipe-transfer-file-ownership`	在用户间转移Drive文件所有权
`recipe-post-mortem-setup`	创建Doc、安排Calendar回顾会议、通过Chat通知
`recipe-save-email-attachments`	将Gmail附件保存至Drive
`recipe-send-team-announcement`	同时通过Gmail和Chat发送团队公告
`recipe-create-feedback-form`	创建Form并通过Gmail分享
`recipe-sync-contacts-to-sheet`	将联系人目录导出至Sheets
`recipe-create-events-from-sheet`	读取Sheets数据并创建Calendar日程
`recipe-generate-report-from-sheet`	读取Sheets数据并创建Docs报告
`recipe-save-email-to-doc`	将Gmail邮件正文归档至Doc
`recipe-batch-reply-to-emails`	查找匹配的邮件并发送标准回复
`recipe-batch-rename-files`	将Drive文件重命名为统一格式
`recipe-create-vacation-responder`	启用Gmail外出自动回复
`recipe-triage-security-alerts`	审核Workspace安全警报
`recipe-deploy-apps-script`	将本地文件推送至Apps Script项目
`recipe-create-meet-space`	创建Meet空间并分享加入链接
`recipe-create-presentation`	创建Slides演示文稿并添加初始幻灯片
`recipe-create-classroom-course`	创建Classroom课程并邀请学生

安装工作流模板：

bash

npx skills add https://github.com/googleworkspace/cli/tree/main/skills/recipe-send-personalized-emails
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/recipe-audit-external-sharing

完整列表：https://github.com/googleworkspace/cli/blob/main/docs/skills.md

MCP Server Integration

MCP服务器集成

gws mcp

starts a Model Context Protocol server over stdio, exposing Google Workspace APIs as structured tools for any MCP-compatible client.

bash

undefined

gws mcp

会启动一个基于Model Context Protocol的服务器，通过标准输入输出通信，将Google Workspace API作为结构化工具暴露给所有兼容MCP的客户端。

bash

undefined

Start MCP server for specific services

为指定服务启动MCP服务器

gws mcp -s drive # Drive only gws mcp -s drive,gmail,calendar # multiple services gws mcp -s all # all services (many tools!)

gws mcp -s drive # 仅Drive服务 gws mcp -s drive,gmail,calendar # 多个服务 gws mcp -s all # 所有服务（工具数量较多！）

Include workflow and helper tools

同时暴露工作流和辅助工具

gws mcp -s drive,gmail -w -e

Compact tool mode — reduces context window usage for LLMs

精简工具模式——减少LLM的上下文窗口占用

gws mcp -s drive,gmail --compact

undefined

gws mcp -s drive,gmail --compact

undefined

MCP Client Configuration

MCP客户端配置

VS Code / Copilot (
settings.json
or
.vscode/mcp.json
):

json

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs"]
    }
  }
}

Claude Desktop (
claude_desktop_config.json
):

json

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs"]
    }
  }
}

Cursor (
.cursor/mcp.json
):

json

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

Gemini CLI Extension:

bash

gws auth setup
gemini extensions install https://github.com/googleworkspace/cli

Installing the Gemini extension gives your Gemini CLI agent direct access to all

gws

commands and skills. The extension automatically inherits your terminal credentials.

Tip: Each service adds roughly 10–80 tools. Keep the list to what you actually need to stay under your client's tool limit (typically 50–100 tools). Use
--compact
flag to reduce context window usage.

VS Code / Copilot（
settings.json
或
.vscode/mcp.json
）：

json

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs"]
    }
  }
}

Claude Desktop（
claude_desktop_config.json
）：

json

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar,sheets,docs"]
    }
  }
}

Cursor（
.cursor/mcp.json
）：

json

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar"]
    }
  }
}

Gemini CLI扩展：

bash

gws auth setup
gemini extensions install https://github.com/googleworkspace/cli

安装Gemini扩展后，Gemini CLI Agent可直接访问所有

gws

命令和技能。扩展会自动继承终端中的凭证。

提示： 每个服务会添加约10–80个工具。请仅保留实际需要的服务，以避免超出客户端的工具数量限制（通常为50–100个工具）。使用
--compact
参数可减少上下文窗口占用。

MCP Flags

MCP参数

Flag	Description
`-s, --services <list>`	Comma-separated services to expose, or `all`
`-w, --workflows`	Also expose workflow tools
`-e, --helpers`	Also expose helper tools
`--compact`	Compact tool mode — reduces tool descriptions to save context window

参数	描述
`-s, --services <list>`	逗号分隔的要暴露的服务列表，或 `all` （所有服务）
`-w, --workflows`	同时暴露工作流工具
`-e, --helpers`	同时暴露辅助工具
`--compact`	精简工具模式——简化工具描述以节省上下文窗口

Advanced Usage

高级用法

Dry Run (preview requests without executing)

试运行（预览请求但不执行）

bash

gws drive files list --params '{"pageSize": 5}' --dry-run

bash

gws drive files list --params '{"pageSize": 5}' --dry-run

Pagination

分页

bash

undefined

bash

undefined

Auto-paginate everything as NDJSON

自动分页并以NDJSON格式输出所有内容

gws drive files list --params '{"pageSize": 100}' --page-all

Limit pages

限制获取页数

gws drive files list --params '{"pageSize": 100}' --page-all --page-limit 5

Delay between pages (rate limiting)

分页请求间隔（限流）

gws drive files list --params '{"pageSize": 100}' --page-all --page-delay 200

undefined

gws drive files list --params '{"pageSize": 100}' --page-all --page-delay 200

undefined

Piping & Processing Output

管道与输出处理

All output is structured JSON. Pipe to

jq

for processing:

bash

undefined

所有输出均为结构化JSON。可通过

jq

进行处理：

bash

undefined

Get just file names

仅获取文件名

gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

Get unread email subjects

获取未读邮件ID

gws gmail users messages list --params '{"userId": "me", "q": "is:unread", "maxResults": 5}' | jq '.messages[].id'

Count events this week

统计本周日程数量

gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-02T00:00:00Z", "timeMax": "2026-03-08T00:00:00Z", "singleEvents": true}' | jq '.items | length'

undefined

gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-02T00:00:00Z", "timeMax": "2026-03-08T00:00:00Z", "singleEvents": true}' | jq '.items | length'

undefined

Multipart Uploads

多部分上传

bash

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

bash

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

Model Armor (Response Sanitization)

Model Armor（响应内容清理）

Scan API responses for prompt injection before they reach your agent:

bash

gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}' \
  --sanitize "projects/P/locations/L/templates/T"

Environment Variable	Description
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	Default Model Armor template
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn` (default) or `block`

在API响应传递给Agent前，扫描是否存在提示注入：

bash

gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}' \\
  --sanitize "projects/P/locations/L/templates/T"

环境变量	描述
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	默认Model Armor模板
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn` （默认）或 `block`

Agent Decision Guide

Agent决策指南

Use this table to decide which

gws

command to run based on what the user is asking:

User Intent	Service	Example Command
List, search, upload, download, share files	`drive`	`gws drive files list`
Create folders, manage permissions	`drive`	`gws drive files create` , `gws drive permissions create`
Read, send, search, label emails	`gmail`	`gws gmail users messages list/send`
Create drafts, manage filters	`gmail`	`gws gmail users drafts create`
View, create, update, delete calendar events	`calendar`	`gws calendar events list/insert/update/delete`
Check availability / free-busy	`calendar`	`gws calendar freebusy query`
Read, write, append spreadsheet data	`sheets`	`gws sheets spreadsheets values get/update/append`
Create spreadsheets, format cells	`sheets`	`gws sheets spreadsheets create/batchUpdate`
Create, read, edit documents	`docs`	`gws docs documents create/get/batchUpdate`
Create, edit presentations	`slides`	`gws slides presentations create/batchUpdate`
Send messages, manage chat spaces	`chat`	`gws chat spaces messages create`
Manage tasks and to-do lists	`tasks`	`gws tasks tasks list/insert/update`
Create meeting links	`meet`	`gws meet spaces create`
Create forms, read responses	`forms`	`gws forms forms create` , `gws forms forms responses list`
Manage contacts and profiles	`people`	`gws people people connections list`
Manage users, groups, devices	`admin`	`gws admin users list` , `gws admin groups list`
Manage notes	`keep`	`gws keep notes list`
Run/deploy Apps Script projects	`apps-script`	`gws apps-script projects list`
Audit logs and usage reports	`admin-reports`	`gws admin-reports activities list`
Manage security alerts	`alertcenter`	`gws alertcenter alerts list`
Manage identity and groups	`cloudidentity`	`gws cloudidentity groups list`
Subscribe to Workspace events	`events`	`gws events subscriptions create`
Manage Google Vault (eDiscovery)	`vault`	`gws vault matters list`
Manage Workspace licenses	`licensing`	`gws licensing licenseAssignments list`
Manage Google Classroom	`classroom`	`gws classroom courses list`
Configure Google Groups settings	`groupssettings`	`gws groupssettings groups get/update`
Manage Workspace subscriptions	`reseller`	`gws reseller subscriptions list`
Sanitize content for safety	`modelarmor`	`gws modelarmor-sanitize-prompt`

根据用户需求选择对应的

gws

命令：

用户需求	服务	示例命令
列出、搜索、上传、下载、分享文件	`drive`	`gws drive files list`
创建文件夹、管理权限	`drive`	`gws drive files create` , `gws drive permissions create`
读取、发送、搜索、标记邮件	`gmail`	`gws gmail users messages list/send`
创建草稿、管理过滤器	`gmail`	`gws gmail users drafts create`
查看、创建、更新、删除日历日程	`calendar`	`gws calendar events list/insert/update/delete`
查看可用性/空闲状态	`calendar`	`gws calendar freebusy query`
读取、写入、追加电子表格数据	`sheets`	`gws sheets spreadsheets values get/update/append`
创建电子表格、格式化单元格	`sheets`	`gws sheets spreadsheets create/batchUpdate`
创建、读取、编辑文档	`docs`	`gws docs documents create/get/batchUpdate`
创建、编辑演示文稿	`slides`	`gws slides presentations create/batchUpdate`
发送消息、管理Chat空间	`chat`	`gws chat spaces messages create`
管理任务和待办事项	`tasks`	`gws tasks tasks list/insert/update`
创建会议链接	`meet`	`gws meet spaces create`
创建表单、读取响应	`forms`	`gws forms forms create` , `gws forms forms responses list`
管理联系人和个人资料	`people`	`gws people people connections list`
管理用户、群组、设备	`admin`	`gws admin users list` , `gws admin groups list`
管理笔记	`keep`	`gws keep notes list`
运行/部署Apps Script项目	`apps-script`	`gws apps-script projects list`
审计日志和使用报告	`admin-reports`	`gws admin-reports activities list`
管理安全警报	`alertcenter`	`gws alertcenter alerts list`
管理身份和群组	`cloudidentity`	`gws cloudidentity groups list`
订阅Workspace事件	`events`	`gws events subscriptions create`
管理Google Vault（电子取证）	`vault`	`gws vault matters list`
管理Workspace许可证	`licensing`	`gws licensing licenseAssignments list`
管理Google Classroom	`classroom`	`gws classroom courses list`
配置Google Groups设置	`groupssettings`	`gws groupssettings groups get/update`
管理Workspace订阅	`reseller`	`gws reseller subscriptions list`
清理内容以确保安全	`modelarmor`	`gws modelarmor-sanitize-prompt`

Environment Variables Reference

环境变量参考

Variable	Description
`GOOGLE_WORKSPACE_CLI_TOKEN`	Pre-obtained OAuth access token
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	Path to credentials JSON (service account or exported)
`GOOGLE_WORKSPACE_CLI_ACCOUNT`	Default account email
`GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER`	User to impersonate (domain-wide delegation)
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	Default Model Armor template
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn` or `block`

变量	描述
`GOOGLE_WORKSPACE_CLI_TOKEN`	预先获取的OAuth访问令牌
`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`	凭证JSON文件路径（服务账号或导出的凭证）
`GOOGLE_WORKSPACE_CLI_ACCOUNT`	默认账号邮箱
`GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER`	要模拟的用户（域范围委派）
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	默认Model Armor模板
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn` 或 `block`

Troubleshooting

故障排除

Error	Fix
"Access blocked" or 403 during login	Add yourself as a test user in OAuth consent screen
"Google hasn't verified this app"	Click Advanced → Continue (safe for personal use)
Too many scopes error	Use `gws auth login -s drive,gmail,sheets` to select fewer services
`gcloud` CLI not found	Install gcloud or set up OAuth manually in Cloud Console
`redirect_uri_mismatch`	Re-create OAuth client as Desktop app type
`accessNotConfigured`	See detailed fix below
Stale credentials	Run `gws auth login` to re-authenticate

错误	解决方法
登录时出现"Access blocked"或403错误	在OAuth consent screen中添加自己为测试用户
出现"Google hasn't verified this app"提示	点击高级 → 继续（个人使用安全）
权限范围过多错误	使用 `gws auth login -s drive,gmail,sheets` 选择更少的服务
未找到 `gcloud` CLI	安装gcloud或在Cloud Console中手动配置OAuth
`redirect_uri_mismatch`	重新创建类型为Desktop app的OAuth客户端
`accessNotConfigured`	查看下方详细解决方法
凭证过期	运行 `gws auth login` 重新认证

API not enabled —

accessNotConfigured

API未启用——

accessNotConfigured

If a required Google API is not enabled for your GCP project, you will see a 403 error:

json

{
  "error": {
    "code": 403,
    "message": "Gmail API has not been used in project 549352339482 ...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}

gws

also prints an actionable hint to stderr:

💡 API not enabled for your GCP project.
   Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   After enabling, wait a few seconds and retry your command.

Steps to fix:

Click the
```
enable_url
```
link (or copy it from the JSON
```
enable_url
```
field).
In the GCP Console, click Enable.
Wait ~10 seconds, then retry your
```
gws
```
command.

Tip: You can also run
gws auth setup
which walks you through enabling all required APIs for your project automatically.

如果GCP项目未启用所需的Google API，会出现403错误：

json

{
  "error": {
    "code": 403,
    "message": "Gmail API has not been used in project 549352339482 ...",
    "reason": "accessNotConfigured",
    "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  }
}

gws

也会在stderr中输出可操作提示：

💡 API未在你的GCP项目中启用。
   点击以下链接启用：https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
   启用后等待几秒，然后重试命令。

解决步骤：

点击
```
enable_url
```
链接（或从JSON的
```
enable_url
```
字段复制）。
在GCP Console中，点击启用。
等待约10秒，然后重试
```
gws
```
命令。

提示： 也可运行
gws auth setup
，它会自动引导完成项目所需API的启用。

Architecture

架构

gws

uses a two-phase parsing strategy:

Read
```
argv[1]
```
to identify the service (e.g.
```
drive
```
)
Fetch the service's Discovery Document (cached 24 hours)
Build a
```
clap::Command
```
tree from the document's resources and methods
Re-parse the remaining arguments
Authenticate, build the HTTP request, execute

All output — success, errors, download metadata — is structured JSON. This means every response is directly parseable by agents without any text extraction.

gws

采用两阶段解析策略：

读取
```
argv[1]
```
以识别服务（如
```
drive
```
）
获取服务的Discovery Document（缓存24小时）
从文档的资源和方法构建
```
clap::Command
```
树
重新解析剩余参数
认证、构建HTTP请求、执行

所有输出——成功结果、错误、下载元数据——均为结构化JSON。这意味着所有响应可直接被Agent解析，无需进行文本提取。

Resources

资源

GitHub Repo: https://github.com/googleworkspace/cli
npm Package: https://www.npmjs.com/package/@googleworkspace/cli
Skills Index (100+ skills): https://github.com/googleworkspace/cli/blob/main/docs/skills.md
Google Discovery API: https://developers.google.com/discovery
Google Workspace APIs: https://developers.google.com/workspace
Releases & Binaries: https://github.com/googleworkspace/cli/releases

GitHub仓库：https://github.com/googleworkspace/cli
npm包：https://www.npmjs.com/package/@googleworkspace/cli
技能索引（100+技能）：https://github.com/googleworkspace/cli/blob/main/docs/skills.md
Google Discovery API：https://developers.google.com/discovery
Google Workspace APIs：https://developers.google.com/workspace
版本与二进制文件：https://github.com/googleworkspace/cli/releases

License

许可证

Apache-2.0

Apache-2.0",

google-workspace-cli

Original

Translation

Google Workspace CLI (gws)

Google Workspace CLI（gws）

How It Works

工作原理

Prerequisites

前置要求

Installation

安装方式

Install globally via npm (recommended — bundles native binaries, no Rust needed)

通过npm全局安装（推荐——捆绑原生二进制文件，无需Rust环境）

Verify installation

验证安装

From GitHub Releases (pre-built binaries)

从GitHub Releases下载预构建二进制文件

Download from: https://github.com/googleworkspace/cli/releases

下载地址：https://github.com/googleworkspace/cli/releases

Build from source (requires Rust toolchain)

从源码构建（需要Rust工具链）

Nix flake

Nix flake方式

Quick Start

快速开始

Authentication

认证方式

Which setup should I use?

如何选择认证方式？

Quick Setup (recommended — requires gcloud CLI)

快速配置（推荐——需安装gcloud CLI）

Scoped Login (for unverified/testing OAuth apps, limited to ~25 scopes)

限定权限范围登录（针对未验证/测试版OAuth应用，最多支持约25个权限范围）

Select only the services you need to stay under the scope limit

仅选择需要的服务，避免超出权限范围限制

Multiple Accounts

多账号管理

Manual OAuth Setup (no gcloud)

手动OAuth配置（无需gcloud）

Headless / CI

无头模式 / CI环境

On a machine with a browser:

在有浏览器的机器上执行：

On the headless machine:

在无头机器上执行：

Service Account (server-to-server)

服务账号（服务器到服务器）

For Domain-Wide Delegation:

针对域范围委派：

Pre-obtained Access Token

预先获取的访问令牌

Browser-Assisted Auth (for AI agents)

浏览器辅助认证（针对AI Agent）

Auth Precedence

认证优先级

Command Structure

命令结构

Global Flags

全局参数

Introspecting Schemas

查看Schema

See the full request/response schema for any method

查看任意方法的完整请求/响应Schema

Core Services — Commands & Examples

核心服务——命令与示例

Google Drive

Google Drive

List files (paginated)

列出文件（分页）

List ALL files (auto-paginate as NDJSON)

列出所有文件（自动分页，输出NDJSON格式）

Search for files

搜索文件

Get file metadata

获取文件元数据

Upload a file

上传文件

Create a folder

创建文件夹

Move a file to a folder

Google Workspace CLI (
`gws`
)

Google Workspace CLI（
`gws`
）