gws

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

npm version license CI status install size


```bash npm install -g @googleworkspace/cli ``` `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. > [!IMPORTANT] > This project is under active development. Expect breaking changes as we march toward v1.0.

Demo

## Contents - [Quick Start](#quick-start) - [Why gws?](#why-gws) - [Authentication](#authentication) - [AI Agent Skills](#ai-agent-skills) - [MCP Server](#mcp-server) - [Advanced Usage](#advanced-usage) - [Architecture](#architecture) - [Development](#development) ## Quick Start ```bash npm install -g @googleworkspace/cli gws auth setup # walks you through Google Cloud project config + OAuth login gws drive files list --params '{"pageSize": 5}' ``` Or build from source: ```bash cargo install --path . ``` A Nix flake is also available at `github:googleworkspace/cli` ```bash nix run github:googleworkspace/cli ``` ## Why gws? **For humans** — stop writing `curl` calls against REST docs. `gws` gives you tab‑completion, `--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. ```bash # 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' ``` ## Authentication The CLI supports multiple auth workflows so it works on your laptop, in CI, and on a server. ### Interactive (local desktop) Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring. ```bash gws auth setup # one-time: creates a Cloud project, enables APIs, logs you in gws auth login # subsequent logins ``` > Requires the [`gcloud` CLI](https://cloud.google.com/sdk/docs/install) to be installed and authenticated. ### Multiple accounts You can authenticate with more than one Google account and switch between them: ```bash gws auth login --account work@corp.com # login and register an account 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..enc` in `~/.config/gws/`, with an `accounts.json` registry tracking defaults. ### 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=` - Credentials: `https://console.cloud.google.com/apis/credentials?project=` 2. Configure OAuth branding/audience if prompted: - App type: **External** (testing mode is fine) - Add your account under **Test users** 3. Create an OAuth client: - Type: **Desktop app** 4. Download the client JSON and save it to: - `~/.config/gws/client_secret.json` Then run: ```bash gws auth login ``` ### 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: ```bash gws auth export --unmasked > credentials.json ``` 3. On the headless machine: ```bash 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. ```bash export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json gws drive files list ``` For Domain-Wide Delegation, add: ```bash export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com ``` ### Pre-obtained Access Token Useful when another tool (e.g. `gcloud`) already mints tokens for your environment. ```bash export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token) ``` ### Precedence | Priority | Source | Set via | | -------- | --------------------------------- | --------------------------------------- | | 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`. Environment variables can also live in a `.env` file. ## AI Agent Skills 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. ```bash # 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 ```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.
## Gemini CLI Extension 1. Authenticate the CLI first: ```bash gws auth setup ``` 2. Install the extension into the Gemini CLI: ```bash 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. ## MCP Server `gws mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio, exposing Google Workspace APIs as structured tools that any MCP-compatible client (Claude Desktop, Gemini CLI, VS Code, etc.) can call. ```bash gws mcp -s drive # expose Drive tools gws mcp -s drive,gmail,calendar # expose multiple services gws mcp -s all # expose all services (many tools!) ``` Configure in your MCP client: ```json { "mcpServers": { "gws": { "command": "gws", "args": ["mcp", "-s", "drive,gmail,calendar"] } } } ``` > [!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). | Flag | Description | | ----------------------- | -------------------------------------------- | | `-s, --services ` | Comma-separated services to expose, or `all` | | `-w, --workflows` | Also expose workflow tools | | `-e, --helpers` | Also expose helper tools | ## Advanced Usage ### Multipart Uploads ```bash 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 ` | Max pages to fetch | 10 | | `--page-delay ` | Delay between pages | 100 ms | ### Model Armor (Response Sanitization) 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. ```bash 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` | ## Architecture `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. ## Troubleshooting ### 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`: ```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:** 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. ## Development ```bash cargo build # dev build cargo clippy -- -D warnings # lint cargo test # unit tests ./scripts/coverage.sh # HTML coverage report → target/llvm-cov/html/ ``` ## License Apache-2.0 ## Disclaimer > [!CAUTION] > This is **not** an officially supported Google product.