Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/googleworkspace-cli/badge.svg)](/listings/googleworkspace-cli)

HTML

<a href="/listings/googleworkspace-cli"><img src="/api/listings/googleworkspace-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The recommended way to install `gws` is to download the pre-built binary for your OS and architecture from the **[GitHub Releases](https://github.com/googleworkspace/cli/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](https://brew.sh/):

brew install googleworkspace-cli

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 510 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">gws</h1>
  2. **One CLI for all of Google Workspace — built for humans and AI agents.**<br>
  3. Drive, Gmail, Calendar, and every Workspace API. Zero boilerplate. Structured JSON output. 40+ agent skills included.
  4. > [!NOTE]
  5. > This is **not** an officially supported Google product.
  6. <p>
  7. <a href="https://www.npmjs.com/package/@googleworkspace/cli"><img src="https://img.shields.io/npm/v/@googleworkspace/cli" alt="npm version"></a>
  8. <a href="https://github.com/googleworkspace/cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/googleworkspace/cli" alt="license"></a>
  9. <a href="https://github.com/googleworkspace/cli/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/googleworkspace/cli/ci.yml?branch=main&label=CI" alt="CI status"></a>
  10. <a href="https://www.npmjs.com/package/@googleworkspace/cli"><img src="https://img.shields.io/npm/unpacked-size/@googleworkspace/cli" alt="install size"></a>
  11. </p>
  12. <br>
  13. ⬇️ **[Download the latest release for your OS](https://github.com/googleworkspace/cli/releases)**
  14. `gws` doesn't ship a static list of commands. It reads Google's own [Discovery Service](https://developers.google.com/discovery) at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, `gws` picks it up automatically.
  15. > [!IMPORTANT]
  16. > This project is under active development. Expect breaking changes as we march toward v1.0.
  17. ## Contents
  18. - [Prerequisites](#prerequisites)
  19. - [Installation](#installation)
  20. - [Quick Start](#quick-start)
  21. - [Why gws?](#why-gws)
  22. - [Authentication](#authentication)
  23. - [AI Agent Skills](#ai-agent-skills)
  24. - [Advanced Usage](#advanced-usage)
  25. - [Environment Variables](#environment-variables)
  26. - [Exit Codes](#exit-codes)
  27. - [Architecture](#architecture)
  28. - [Troubleshooting](#troubleshooting)
  29. - [Development](#development)
  30. ## Prerequisites
  31. - **Node.js 18+** — for `npm install` (or download a pre-built binary from [GitHub Releases](https://github.com/googleworkspace/cli/releases))
  32. - **A Google Cloud project** — required for OAuth credentials. You can create one via the [Google Cloud Console](https://console.cloud.google.com/) or with the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install) or with the `gws auth setup` command.
  33. - **A Google account** with access to Google Workspace
  34. ## Installation
  35. The recommended way to install `gws` is to download the pre-built binary for your OS and architecture from the **[GitHub Releases](https://github.com/googleworkspace/cli/releases)** page. Extract the archive and place the `gws` binary in your `$PATH`.
  36. For convenience, you can also use `npm` to automate downloading the appropriate binary from GitHub Releases:
  37. ```bash
  38. npm install -g @googleworkspace/cli
  39. ```
  40. Or build from source:
  41. ```bash
  42. cargo install --git https://github.com/googleworkspace/cli --locked
  43. ```
  44. A Nix flake is also available at `github:googleworkspace/cli`
  45. ```bash
  46. nix run github:googleworkspace/cli
  47. ```
  48. On macOS and Linux, you can also install via [Homebrew](https://brew.sh/):
  49. ```bash
  50. brew install googleworkspace-cli
  51. ```
  52. ## Quick Start
  53. ```bash
  54. gws auth setup # walks you through Google Cloud project config
  55. gws auth login # subsequent OAuth login
  56. gws drive files list --params '{"pageSize": 5}'
  57. ```
  58. ## Why gws?
  59. **For humans** — stop writing `curl` calls against REST docs. `gws` gives you `--help` on every resource, `--dry-run` to preview requests, and auto‑pagination.
  60. **For AI agents** — every response is structured JSON. Pair it with the included agent skills and your LLM can manage Workspace without custom tooling.
  61. ```bash
  62. # List the 10 most recent files
  63. gws drive files list --params '{"pageSize": 10}'
  64. # Create a spreadsheet
  65. gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'
  66. # Send a Chat message
  67. gws chat spaces messages create \
  68. --params '{"parent": "spaces/xyz"}' \
  69. --json '{"text": "Deploy complete."}' \
  70. --dry-run
  71. # Introspect any method's request/response schema
  72. gws schema drive.files.list
  73. # Stream paginated results as NDJSON
  74. gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'
  75. ```
  76. ## Authentication
  77. The CLI supports multiple auth workflows so it works on your laptop, in CI, and on a server.
  78. ### Which setup should I use?
  79. | I have… | Use |
  80. |---|---|
  81. | `gcloud` installed and authenticated | [`gws auth setup`](#interactive-local-desktop) (fastest) |
  82. | A GCP project but no `gcloud` | [Manual OAuth setup](#manual-oauth-setup-google-cloud-console) |
  83. | An existing OAuth access token | [`GOOGLE_WORKSPACE_CLI_TOKEN`](#pre-obtained-access-token) |
  84. | Existing Credentials | [`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`](#service-account-server-to-server) |
  85. ### Interactive (local desktop)
  86. 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`).
  87. ```bash
  88. gws auth setup # one-time: creates a Cloud project, enables APIs, logs you in
  89. gws auth login # subsequent scope selection and login
  90. ```
  91. > `gws auth setup` requires the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install). If you don't have `gcloud`, use the [manual setup](#manual-oauth-setup-google-cloud-console) below instead.
  92. > [!WARNING]
  93. > **Scope limits in testing mode:** If your OAuth app is unverified (testing mode),
  94. > Google limits consent to ~25 scopes. The `recommended` scope preset includes 85+
  95. > scopes and **will fail** for unverified apps (especially for `@gmail.com` accounts).
  96. > Choose individual services instead to filter the scope picker:
  97. > ```bash
  98. > gws auth login -s drive,gmail,sheets
  99. > ```
  100. ### Manual OAuth setup (Google Cloud Console)
  101. Use this when `gws auth setup` cannot automate project/client creation, or when you want explicit control.
  102. 1. Open Google Cloud Console in the target project:
  103. - OAuth consent screen: `https://console.cloud.google.com/apis/credentials/consent?project=<PROJECT_ID>`
  104. - Credentials: `https://console.cloud.google.com/apis/credentials?project=<PROJECT_ID>`
  105. 2. Configure OAuth branding/audience if prompted:
  106. - App type: **External** (testing mode is fine)
  107. 3. Add your account under **Test users**
  108. 4. Create an OAuth client:
  109. - Type: **Desktop app**
  110. 5. Download the client JSON and save it to:
  111. - `~/.config/gws/client_secret.json`
  112. > [!IMPORTANT]
  113. > **You must add yourself as a test user.** In the OAuth consent screen, click
  114. > **Test users → Add users** and enter your Google account email. Without this,
  115. > login will fail with a generic "Access blocked" error.
  116. Then run:
  117. ```bash
  118. gws auth login
  119. ```
  120. ### Browser-assisted auth (human or agent)
  121. You can complete OAuth either manually or with browser automation.
  122. - **Human flow**: run `gws auth login`, open the printed URL, approve scopes.
  123. - **Agent-assisted flow**: the agent opens the URL, selects account, handles consent prompts, and returns control once the localhost callback succeeds.
  124. If consent shows **"Google hasn't verified this app"** (testing mode), click **Continue**.
  125. If scope checkboxes appear, select required scopes (or **Select all**) before continuing.
  126. ### Headless / CI (export flow)
  127. 1. Complete interactive auth on a machine with a browser.
  128. 2. Export credentials:
  129. ```bash
  130. gws auth export --unmasked > credentials.json
  131. ```
  132. 3. On the headless machine:
  133. ```bash
  134. export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
  135. gws drive files list # just works
  136. ```
  137. ### Service Account (server-to-server)
  138. Point to your key file; no login needed.
  139. ```bash
  140. export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
  141. gws drive files list
  142. ```
  143. ### Pre-obtained Access Token
  144. Useful when another tool (e.g. `gcloud`) already mints tokens for your environment.
  145. ```bash
  146. export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
  147. ```
  148. ### Precedence
  149. | Priority | Source | Set via |
  150. | -------- | ---------------------- | --------------------------------------- |
  151. | 1 | Access token | `GOOGLE_WORKSPACE_CLI_TOKEN` |
  152. | 2 | Credentials file | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` |
  153. | 3 | Encrypted credentials | `gws auth login` |
  154. | 4 | Plaintext credentials | `~/.config/gws/credentials.json` |
  155. Environment variables can also live in a `.env` file.
  156. ## AI Agent Skills
  157. 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](docs/skills.md) for the complete list.
  158. ```bash
  159. # Install all skills at once
  160. npx skills add https://github.com/googleworkspace/cli
  161. # Or pick only what you need
  162. npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
  163. npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
  164. ```
  165. <details>
  166. <summary>OpenClaw setup</summary>
  167. ```bash
  168. # Symlink all skills (stays in sync with repo)
  169. ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/
  170. # Or copy specific skills
  171. cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/
  172. ```
  173. The `gws-shared` skill includes an `install` block so OpenClaw auto-installs the CLI via `npm` if `gws` isn't on PATH.
  174. </details>
  175. ## Gemini CLI Extension
  176. 1. Authenticate the CLI first:
  177. ```bash
  178. gws auth setup
  179. ```
  180. 2. Install the extension into the Gemini CLI:
  181. ```bash
  182. gemini extensions install https://github.com/googleworkspace/cli
  183. ```
  184. 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.
  185. ## Advanced Usage
  186. ### Multipart Uploads
  187. ```bash
  188. gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf
  189. ```
  190. ### Pagination
  191. | Flag | Description | Default |
  192. | ------------------- | ---------------------------------------------- | ------- |
  193. | `--page-all` | Auto-paginate, one JSON line per page (NDJSON) | off |
  194. | `--page-limit <N>` | Max pages to fetch | 10 |
  195. | `--page-delay <MS>` | Delay between pages | 100 ms |
  196. ### Google Sheets — Shell Escaping
  197. Sheets ranges use `!` which bash interprets as history expansion. Always wrap values in **single quotes**:
  198. ```bash
  199. # Read cells A1:C10 from "Sheet1"
  200. gws sheets spreadsheets values get \
  201. --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "Sheet1!A1:C10"}'
  202. # Append rows
  203. gws sheets spreadsheets values append \
  204. --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' \
  205. --json '{"values": [["Name", "Score"], ["Alice", 95]]}'
  206. ```
  207. ### Helper Commands
  208. 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.
  209. 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.
  210. Run `gws <service> --help` to see both Discovery methods and helper commands together.
  211. ```bash
  212. gws gmail --help # shows +send, +reply, +reply-all, +forward, +triage, +watch …
  213. gws calendar --help # shows +insert, +agenda …
  214. gws drive --help # shows +upload …
  215. ```
  216. **Full helper reference:**
  217. | Service | Command | Description |
  218. |---------|---------|-------------|
  219. | `gmail` | `+send` | Send an email |
  220. | `gmail` | `+reply` | Reply to a message (handles threading automatically) |
  221. | `gmail` | `+reply-all` | Reply-all to a message |
  222. | `gmail` | `+forward` | Forward a message to new recipients |
  223. | `gmail` | `+triage` | Show unread inbox summary (sender, subject, date) |
  224. | `gmail` | `+watch` | Watch for new emails and stream them as NDJSON |
  225. | `sheets` | `+append` | Append a row to a spreadsheet |
  226. | `sheets` | `+read` | Read values from a spreadsheet |
  227. | `docs` | `+write` | Append text to a document |
  228. | `chat` | `+send` | Send a message to a space |
  229. | `drive` | `+upload` | Upload a file with automatic metadata |
  230. | `calendar` | `+insert` | Create a new event |
  231. | `calendar` | `+agenda` | Show upcoming events (uses Google account timezone; override with `--timezone`) |
  232. | `script` | `+push` | Replace all files in an Apps Script project with local files |
  233. | `workflow` | `+standup-report` | Today's meetings + open tasks as a standup summary |
  234. | `workflow` | `+meeting-prep` | Prepare for your next meeting: agenda, attendees, and linked docs |
  235. | `workflow` | `+email-to-task` | Convert a Gmail message into a Google Tasks entry |
  236. | `workflow` | `+weekly-digest` | Weekly summary: this week's meetings + unread email count |
  237. | `workflow` | `+file-announce` | Announce a Drive file in a Chat space |
  238. | `events` | `+subscribe` | Subscribe to Workspace events and stream them as NDJSON |
  239. | `events` | `+renew` | Renew/reactivate Workspace Events subscriptions |
  240. | `modelarmor` | `+sanitize-prompt` | Sanitize a user prompt through a Model Armor template |
  241. | `modelarmor` | `+sanitize-response` | Sanitize a model response through a Model Armor template |
  242. | `modelarmor` | `+create-template` | Create a new Model Armor template |
  243. **Examples:**
  244. ```bash
  245. # Send an email
  246. gws gmail +send --to alice@example.com --subject "Hello" --body "Hi there"
  247. # Reply to a message
  248. gws gmail +reply --message-id MESSAGE_ID --body "Thanks!"
  249. # Append a row to a spreadsheet
  250. gws sheets +append --spreadsheet SPREADSHEET_ID --values "Alice,95"
  251. # Show today's calendar agenda
  252. gws calendar +agenda
  253. # Upload a file to Drive
  254. gws drive +upload ./report.pdf --name "Q1 Report"
  255. # Morning standup summary
  256. gws workflow +standup-report
  257. # Show today's agenda in a specific timezone
  258. gws calendar +agenda --today --timezone America/New_York
  259. ```
  260. ### Model Armor (Response Sanitization)
  261. Integrate [Google Cloud Model Armor](https://cloud.google.com/security/products/model-armor) to scan API responses for prompt injection before they reach your agent.
  262. ```bash
  263. gws gmail users messages get --params '...' \
  264. --sanitize "projects/P/locations/L/templates/T"
  265. ```
  266. | Variable | Description |
  267. | ---------------------------------------- | ---------------------------- |
  268. | `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | Default Model Armor template |
  269. | `GOOGLE_WORKSPACE_CLI_SANITIZE_MODE` | `warn` (default) or `block` |
  270. ## Environment Variables
  271. All variables are optional. See [`.env.example`](.env.example) for a copy-paste template.
  272. | Variable | Description |
  273. |---|---|
  274. | `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained OAuth2 access token (highest priority) |
  275. | `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to OAuth credentials JSON (user or service account) |
  276. | `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID (alternative to `client_secret.json`) |
  277. | `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret (paired with `CLIENT_ID`) |
  278. | `GOOGLE_WORKSPACE_CLI_CONFIG_DIR` | Override config directory (default: `~/.config/gws`) |
  279. | `GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE` | Default Model Armor template |
  280. | `GOOGLE_WORKSPACE_CLI_SANITIZE_MODE` | `warn` (default) or `block` |
  281. | `GOOGLE_WORKSPACE_CLI_LOG` | Log level for stderr (e.g., `gws=debug`). Off by default. |
  282. | `GOOGLE_WORKSPACE_CLI_LOG_FILE` | Directory for JSON log files with daily rotation. Off by default. |
  283. | `GOOGLE_WORKSPACE_PROJECT_ID` | GCP project ID override for quota/billing and fallback for helper commands |
  284. Environment variables can also be set in a `.env` file (loaded via [dotenvy](https://crates.io/crates/dotenvy)).
  285. ## Exit Codes
  286. `gws` uses structured exit codes so scripts can branch on the failure type without parsing error output.
  287. | Code | Meaning | Example cause |
  288. |------|---------|---------------|
  289. | `0` | Success | Command completed normally |
  290. | `1` | API error | Google returned a 4xx/5xx response |
  291. | `2` | Auth error | Credentials missing, expired, or invalid |
  292. | `3` | Validation error | Bad arguments, unknown service, invalid flag |
  293. | `4` | Discovery error | Could not fetch the API schema document |
  294. | `5` | Internal error | Unexpected failure |
  295. ```bash
  296. gws drive files list --params '{"fileId": "bad"}'
  297. echo $? # 1 — API error
  298. gws unknown-service files list
  299. echo $? # 3 — validation error (unknown service)
  300. ```
  301. ## Architecture
  302. `gws` uses a **two-phase parsing** strategy:
  303. 1. Read `argv[1]` to identify the service (e.g. `drive`)
  304. 2. Fetch the service's Discovery Document (cached 24 h)
  305. 3. Build a `clap::Command` tree from the document's resources and methods
  306. 4. Re-parse the remaining arguments
  307. 5. Authenticate, build the HTTP request, execute
  308. All output — success, errors, download metadata — is structured JSON.
  309. ## Troubleshooting
  310. ### "Access blocked" or 403 during login
  311. Your OAuth app is in **testing mode** and your account is not listed as a test user.
  312. **Fix:** Open the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) in your GCP project → **Test users** → **Add users** → enter your Google account email. Then retry `gws auth login`.
  313. ### "Google hasn't verified this app"
  314. Expected when your app is in testing mode. Click **Advanced** → **Go to \<app name\> (unsafe)** to proceed. This is safe for personal use; verification is only required to publish the app to other users.
  315. ### Too many scopes / consent screen error
  316. Unverified (testing mode) apps are limited to ~25 OAuth scopes. The `recommended` scope preset includes many scopes and will exceed this limit.
  317. **Fix:** Select only the scopes you need:
  318. ```bash
  319. gws auth login --scopes drive,gmail,calendar
  320. ```
  321. ### `gcloud` CLI not found
  322. `gws auth setup` requires the `gcloud` CLI to automate project creation. You have three options:
  323. 1. [Install gcloud](https://cloud.google.com/sdk/docs/install) and use `gcloud` directly.
  324. 2. Re-run `gws auth setup` which wraps `gcloud` calls.
  325. 3. Skip `gcloud` entirely — set up OAuth credentials manually in the [Cloud Console](#manual-oauth-setup-google-cloud-console)
  326. ### `redirect_uri_mismatch`
  327. The OAuth client was not created as a **Desktop app** type. In the [Credentials](https://console.cloud.google.com/apis/credentials) page, delete the existing client, create a new one with type **Desktop app**, and download the new JSON.
  328. ### API not enabled — `accessNotConfigured`
  329. If a required Google API is not enabled for your GCP project, you will see a
  330. 403 error with reason `accessNotConfigured`:
  331. ```json
  332. {
  333. "error": {
  334. "code": 403,
  335. "message": "Gmail API has not been used in project 549352339482 ...",
  336. "reason": "accessNotConfigured",
  337. "enable_url": "https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482"
  338. }
  339. }
  340. ```
  341. `gws` also prints an actionable hint to **stderr**:
  342. ```
  343. 💡 API not enabled for your GCP project.
  344. Enable it at: https://console.developers.google.com/apis/api/gmail.googleapis.com/overview?project=549352339482
  345. After enabling, wait a few seconds and retry your command.
  346. ```
  347. **Steps to fix:**
  348. 1. Click the `enable_url` link (or copy it from the `enable_url` JSON field).
  349. 2. In the GCP Console, click **Enable**.
  350. 3. Wait ~10 seconds, then retry your `gws` command.
  351. > [!TIP]
  352. > You can also run `gws auth setup` which walks you through enabling all required
  353. > APIs for your project automatically.
  354. ## Development
  355. ```bash
  356. cargo build # dev build
  357. cargo clippy -- -D warnings # lint
  358. cargo test # unit tests
  359. ./scripts/coverage.sh # HTML coverage report → target/llvm-cov/html/
  360. ```
  361. ## License
  362. Apache-2.0
  363. ## Disclaimer
  364. > [!CAUTION]
  365. > This is **not** an officially supported Google product.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.