一个用于所有 Google Workspace 的 CLI——同时为人类和 AI 代理构建。
覆盖 Drive、Gmail、Calendar 和每一个 Workspace API。零样板代码。结构化 JSON 输出。包含 40+ 代理技能。

注意

这不是官方支持的 Google 产品。

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

gws 并不提供一份静态的命令列表。它在运行时读取 Google 的发现服务并动态构建整个命令界面。当 Google Workspace 新增某个 API 端点或方法时，gws 会自动获取到。

重要

此项目正在积极开发中。在向 v1.0 迈进的过程中，预计会有破坏性变更。

• Node.js 18+ —— 用于 npm install（或从 GitHub Releases 下载预构建二进制文件）
• 一个 Google Cloud 项目 —— OAuth 凭证需要。你可以通过 Google Cloud Console 或 gcloud CLI 创建，也可以使用 gws auth setup 命令。
• 一个能够访问 Google Workspace 的 Google 账号

安装 gws 的推荐方式是下载对应你操作系统和架构的预构建二进制文件，从 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}'

针对人类用户 —— 不必再对着 REST 文档编写 curl 调用。gws 提供每个资源的 --help、--dry-run 预览请求以及自动分页。

针对 AI 代理 —— 每个响应都是结构化的 JSON。配合内置的代理技能，你的大语言模型无需自定义工具即可管理 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 环境中，也可以在服务器上使用。

我该使用哪种设置？

交互式（本地桌面）

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

gws auth setup # 一次性操作：创建一个 Cloud 项目，启用 API，让你登录 gws auth login # 后续的作用域选择和登录

gws auth setup 需要 gcloud CLI。如果你没有 gcloud，请改用下面的手动设置。

警告

测试模式下的作用域限制： 如果你的 OAuth 应用未经验证（测试模式），Google 将同意限制为约 25 个作用域。recommended 作用域预设包含 85+ 个作用域，会失败（尤其是对于 @gmail.com 账号）。此时请选择个别服务以过滤作用域选择器：

gws auth login -s drive,gmail,sheets

手动 OAuth 设置（Google Cloud Console）

当 gws auth setup 无法自动创建项目/客户端，或者你需要显式控制时，可使用此方式。

1. 在目标项目中打开 Google Cloud Console：
   • OAuth 同意屏幕：https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>
   • 凭据：https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>
2. 如果出现提示，配置 OAuth 品牌/受众：
   • 应用类型：外部（测试模式即可）
3. 在测试用户中添加你的账号
4. 创建一个 OAuth 客户端：
5. 下载客户端 JSON 并保存到：
   • ~/.config/gws/client_secret.json

重要

你必须将自己添加为测试用户。 在 OAuth 同意屏幕中，点击测试用户 → 添加用户并输入你的 Google 账号邮箱。如果不这样做，登录将失败并显示通用的“访问被阻止”错误。

然后运行：

浏览器辅助认证（人类或代理）

你可以手动完成 OAuth，或者使用浏览器自动化。

• 人类流程：运行 gws auth login，打开打印出的 URL，批准所需作用域。
• 代理辅助流程：代理打开 URL，选择账号，处理同意提示，并在本地主机回调成功后返回控制权。

如果同意屏幕显示**“Google 尚未验证此应用”（测试模式），请点击继续**。如果出现作用域复选框，选择所需作用域（或全选）后继续。

Headless/CI（导出流程）

1. 在一台有浏览器的机器上完成交互式认证。

2. 导出凭据：

   gws auth export --unmasked > credentials.json

3. 在 headless 机器上：

   export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json gws drive files list # 正常运行

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

指向你的密钥文件；无需登录。

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

预获取的访问令牌

当其他工具（如 gcloud）已经为你的环境生成了令牌时，可以使用这种方式。

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

优先级	来源	设置方式
1	访问令牌	GOOGLE_WORKSPACE_CLI_TOKEN
2	凭据文件	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3	加密凭据	gws auth login
4	明文凭据	~/.config/gws/credentials.json

环境变量也可以存放在 .env 文件中。

该仓库提供了 100 多个代理技能（SKILL.md 文件）——每个受支持的 API 对应一个，再加上面向常见工作流的高级辅助工具，以及 50 个针对 Gmail、Drive、Docs、Calendar 和 Sheets 的精选配方。完整列表请参见 技能索引。

一次性安装所有技能

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

或者只挑选你需要的

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

OpenClaw 设置

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

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

或者复制特定技能

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

gws-shared 技能包含一个 install 块，这样如果 gws 不在 PATH 上，OpenClaw 可以通过 npm 自动安装 CLI。

1. 首先认证 CLI：

2. 将扩展安装到 Gemini CLI：

   gemini extensions install https://github.com/googleworkspace/cli

安装此扩展后，你的 Gemini CLI 代理将能直接访问所有 gws 命令和 Google Workspace 代理技能。由于 gws 自行安全地处理认证，你只需在使用代理之前在终端中认证一次，扩展将自动继承你的凭据。

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

分页

标志	描述	默认值
--page-all	自动分页，每页一行 JSON（NDJSON）	关闭
--page-limit <N>	要获取的最大页数	10
--page-delay <MS>	页之间的延迟（毫秒）	100 ms

Google Sheets——Shell 转义

Sheets 范围使用 !，bash 会将其解释为历史扩展。始终将值用单引号括起来：

从 "Sheet1" 读取单元格 A1:C10

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

添加行

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

部分服务在自动生成的发现界面之外，还提供了手工编写的高阶辅助命令。这些辅助命令前缀为 +，以便在视觉上区分，并且永远不会与发现生成的方法名冲突。

时间感知的辅助命令（+agenda、+standup-report、+weekly-digest、+meeting-prep）会自动使用你的 Google 账号时区（从 Calendar Settings API 获取，缓存 24 小时）。可以在 +agenda 上使用 --timezone/--tz 进行覆盖，或设置 --timezone 标志以显式控制。

运行 gws <service> --help 可以同时查看发现方法和辅助命令。

gws gmail --help # 显示 +send、+reply、+reply-all、+forward、+triage、+watch … gws calendar --help # 显示 +insert、+agenda … gws drive --help # 显示 +upload …

完整辅助命令参考：

服务	命令	描述
gmail	+send	发送一封邮件
gmail	+reply	回复一条消息（自动处理邮件线程）
gmail	+reply-all	回复全部
gmail	+forward	将消息转发给新收件人
gmail	+triage	显示未读收件箱摘要（发件人、主题、日期）
gmail	+watch	监听新邮件并以 NDJSON 流式输出
sheets	+append	向电子表格追加一行
sheets	+read	从电子表格读取值
docs	+write	向文档追加文本
chat	+send	向聊天室发送消息
drive	+upload	上传文件并自动添加元数据
calendar	+insert	创建一个新事件
calendar	+agenda	显示即将发生的事件（使用 Google 账号时区；可用 --timezone 覆盖）
script	+push	用本地文件替换 Apps Script 项目中的所有文件
workflow	+standup-report	今天的会议 + 待办任务，生成站会摘要
workflow	+meeting-prep	为下一次会议做准备：议程、参会者和关联文档
workflow	+email-to-task	将 Gmail 消息转换为 Google Tasks 条目
workflow	+weekly-digest	每周摘要：本周会议 + 未读邮件计数
workflow	+file-announce	在 Chat 聊天室中公告一个 Drive 文件
events	+subscribe	订阅 Workspace 事件并以 NDJSON 流式输出
events	+renew	续订/重新激活 Workspace 事件订阅
modelarmor	+sanitize-prompt	通过 Model Armor 模板净化用户提示
modelarmor	+sanitize-response	通过 Model Armor 模板净化模型响应
modelarmor	+create-template	创建一个新的 Model Armor 模板

示例：

发送一封邮件

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

上传一个文件到 Drive

gws drive +upload ./report.pdf --name "Q1 Report"

早晨站会摘要

gws workflow +standup-report

以特定时区显示今日议程

gws calendar +agenda --today --timezone America/New_York

Model Armor（响应净化）

集成 Google Cloud Model Armor，在 API 响应到达代理之前扫描是否存在提示注入。

gws gmail users messages get --params '...'
--sanitize "projects/P/locations/L/templates/T"

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

所有变量都是可选的。参见 [.env.example](/googleworkspa

One CLI for all of Google Workspace — built for humans and AI agents.
Drive, Gmail, Calendar, and every Workspace API. Zero boilerplate. Structured JSON output. 40+ agent skills included.

Note

This is not an officially supported Google product.

⬇️ Download the latest release for your OS

gws doesn't ship a static list of commands. It reads Google's own Discovery Service at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, gws picks it up automatically.

Important

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

• 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 or with the gcloud CLI or with the gws auth setup command.
• A Google account with access to Google Workspace

The recommended way to install gws is to download the pre-built binary for your OS and architecture from the GitHub Releases page. Extract the archive and place the gws binary in your $PATH.

For convenience, you can also use npm to automate downloading the appropriate binary from GitHub Releases:

npm install -g @googleworkspace/cli

Or build from source:

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

A Nix flake is also available at github:googleworkspace/cli

nix run github:googleworkspace/cli

On macOS and Linux, you can also install via Homebrew:

brew install googleworkspace-cli


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

For humans — stop writing curl calls against REST docs. gws gives you --help on every resource, --dry-run to preview requests, and auto‑pagination.

For AI agents — every response is structured JSON. Pair it with the included agent skills and your LLM can manage Workspace without custom tooling.

# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# Introspect any method's request/response schema
gws schema drive.files.list

# Stream paginated results as NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

The CLI supports multiple auth workflows so it works on your laptop, in CI, and on a server.

Which setup should I use?

Interactive (local desktop)

Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring (or ~/.config/gws/.encryption_key when GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file).

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

gws auth setup requires the gcloud CLI. If you don't have gcloud, use the manual setup below instead.

Warning

Scope limits in testing mode: If your OAuth app is unverified (testing mode), Google limits consent to ~25 scopes. The recommended scope preset includes 85+ scopes and will fail for unverified apps (especially for @gmail.com accounts). Choose individual services instead to filter the scope picker:

gws auth login -s drive,gmail,sheets

Manual OAuth setup (Google Cloud Console)

Use this when gws auth setup cannot automate project/client creation, or when you want explicit control.

1. 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>
2. Configure OAuth branding/audience if prompted:
   • App type: External (testing mode is fine)
3. Add your account under Test users
4. Create an OAuth client:
5. Download the client JSON and save it 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:

Browser-assisted auth (human or agent)

You can complete OAuth either manually or with browser automation.

• Human flow : run gws auth login, open the printed URL, approve scopes.
• Agent-assisted flow : the agent opens the URL, selects 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.

Headless / CI (export flow)

1. Complete interactive auth on a machine with a browser.

2. Export credentials:

   gws auth export --unmasked > credentials.json
   

3. On the headless machine:

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

Service Account (server-to-server)

Point to your key file; no login needed.

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

Pre-obtained Access Token

Useful when another tool (e.g. gcloud) already mints tokens for your environment.

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

Priority	Source	Set via
1	Access token	GOOGLE_WORKSPACE_CLI_TOKEN
2	Credentials file	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3	Encrypted credentials	gws auth login
4	Plaintext credentials	~/.config/gws/credentials.json

Environment variables can also live in a .env file.

The repo ships 100+ Agent Skills (SKILL.md files) — one for every supported API, plus higher-level helpers for common workflows and 50 curated recipes for Gmail, Drive, Docs, Calendar, and Sheets. See the full Skills Index for the complete list.

# Install all skills at once
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

OpenClaw setup

# 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.

1. Authenticate the CLI first:

2. Install the extension into the Gemini CLI:

   gemini extensions install https://github.com/googleworkspace/cli
   

Installing this extension gives your Gemini CLI agent direct access to all gws commands and Google Workspace agent skills. Because gws handles its own authentication securely, you simply need to authenticate your terminal once prior to using the agent, and the extension will automatically inherit your credentials.

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

Pagination

Flag	Description	Default
--page-all	Auto-paginate, one JSON line per page (NDJSON)	off
--page-limit <N>	Max pages to fetch	10
--page-delay <MS>	Delay between pages	100 ms

Google Sheets — Shell Escaping

Sheets ranges use ! which bash interprets as history expansion. Always wrap values in single quotes :

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

# Append rows
gws sheets spreadsheets values append \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["Name", "Score"], ["Alice", 95]]}'

Some services ship hand-crafted helper commands alongside the auto-generated Discovery surface. Helper commands are prefixed with + so they are visually distinct and never collide with Discovery-generated method names.

Time-aware helpers (+agenda, +standup-report, +weekly-digest, +meeting-prep) automatically use your Google account timezone (fetched from Calendar Settings API and cached for 24 hours). Override with --timezone/--tz on +agenda, or set the --timezone flag for explicit control.

Run gws <service> --help to see both Discovery methods and helper commands together.

gws gmail --help      # shows +send, +reply, +reply-all, +forward, +triage, +watch …
gws calendar --help   # shows +insert, +agenda …
gws drive --help      # shows +upload …

Full helper reference:

Service	Command	Description
gmail	+send	Send an email
gmail	+reply	Reply to a message (handles threading automatically)
gmail	+reply-all	Reply-all to a message
gmail	+forward	Forward a message to new recipients
gmail	+triage	Show unread inbox summary (sender, subject, date)
gmail	+watch	Watch for new emails and stream them as NDJSON
sheets	+append	Append a row to a spreadsheet
sheets	+read	Read values from a spreadsheet
docs	+write	Append text to a document
chat	+send	Send a message to a space
drive	+upload	Upload a file with automatic metadata
calendar	+insert	Create a new event
calendar	+agenda	Show upcoming events (uses Google account timezone; override with --timezone)
script	+push	Replace all files in an Apps Script project with local files
workflow	+standup-report	Today's meetings + open tasks as a standup summary
workflow	+meeting-prep	Prepare for your next meeting: agenda, attendees, and linked docs
workflow	+email-to-task	Convert a Gmail message into a Google Tasks entry
workflow	+weekly-digest	Weekly summary: this week's meetings + unread email count
workflow	+file-announce	Announce a Drive file in a Chat space
events	+subscribe	Subscribe to Workspace events and stream them as NDJSON
events	+renew	Renew/reactivate Workspace Events subscriptions
modelarmor	+sanitize-prompt	Sanitize a user prompt through a Model Armor template
modelarmor	+sanitize-response	Sanitize a model response through a Model Armor template
modelarmor	+create-template	Create a new Model Armor template

Examples:

# Send an email
gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"

# Reply to a message
gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"

# Append a row to a spreadsheet
gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"

# Show today's calendar agenda
gws calendar +agenda

# Upload a file to Drive
gws drive +upload ./report.pdf --name "Q1 Report"

# Morning standup summary
gws workflow +standup-report

# Show today's agenda in a specific timezone
gws calendar +agenda --today --timezone America/New_York

Model Armor (Response Sanitization)

Integrate Google Cloud Model Armor to scan API responses for prompt injection before they reach your agent.

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

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

All variables are optional. See .env.example for a copy-paste template.

Variable	Description
GOOGLE_WORKSPACE_CLI_TOKEN	Pre-obtained OAuth2 access token (highest priority)
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	Path to OAuth credentials JSON (user or service account)
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth client ID (alternative to client_secret.json)
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth client secret (paired with CLIENT_ID)
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	Override config directory (default: ~/.config/gws)
GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE	Default Model Armor template
GOOGLE_WORKSPACE_CLI_SANITIZE_MODE	warn (default) or block
GOOGLE_WORKSPACE_CLI_LOG	Log level for stderr (e.g., gws=debug). Off by default.
GOOGLE_WORKSPACE_CLI_LOG_FILE	Directory for JSON log files with daily rotation. Off by default.
GOOGLE_WORKSPACE_PROJECT_ID	GCP project ID override for quota/billing and fallback for helper commands

Environment variables can also be set in a .env file (loaded via dotenvy).

gws uses structured exit codes so scripts can branch on the failure type without parsing error output.

Code	Meaning	Example cause
0	Success	Command completed normally
1	API error	Google returned a 4xx/5xx response
2	Auth error	Credentials missing, expired, or invalid
3	Validation error	Bad arguments, unknown service, invalid flag
4	Discovery error	Could not fetch the API schema document
5	Internal error	Unexpected failure

gws drive files list --params '{"fileId": "bad"}'
echo $?   # 1 — API error

gws unknown-service files list
echo $?   # 3 — validation error (unknown service)

gws uses a two-phase parsing strategy:

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

All output — success, errors, download metadata — is structured JSON.

"Access blocked" or 403 during login

Your OAuth app is in testing mode and your account is not listed as a test user.

Fix: Open the OAuth consent screen in your GCP project → Test users → Add users → enter your Google account email. Then retry gws auth login.

"Google hasn't verified this app"

Expected when your app is in testing mode. Click Advanced → Go to (unsafe) to proceed. This is safe for personal use; verification is only required to publish the app to other users.

Too many scopes / consent screen error

Unverified (testing mode) apps are limited to ~25 OAuth scopes. The recommended scope preset includes many scopes and will exceed this limit.

Fix: Select only the scopes you need:

gws auth login --scopes drive,gmail,calendar

gws auth setup requires the gcloud CLI to automate project creation. You have three options:

1. Install gcloud and use gcloud directly.
2. Re-run gws auth setup which wraps gcloud calls.
3. Skip gcloud entirely — set up OAuth credentials manually in the Cloud Console

The OAuth client was not created as a Desktop app type. In the Credentials page, delete the existing client, create a new one with type Desktop app , and download the new JSON.

API not enabled — accessNotConfigured

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

{
  "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:

1. Click the enable_url link (or copy it from the enable_url JSON field).
2. In the GCP Console, click Enable.
3. 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.

cargo build                       # dev build
cargo clippy -- -D warnings       # lint
cargo test                        # unit tests
./scripts/coverage.sh             # HTML coverage report → target/llvm-cov/html/

Apache-2.0

Caution

This is not an officially supported Google product.