Interact with all Google Workspace APIs via the gws CLI. Use when managing Drive files, sending/reading Gmail, creating Calendar events, reading/writing Sheets/Docs/Slides, managing Chat spaces, contacts, Admin users/groups, Vault eDiscovery, Classroom, Apps Script, Workspace Events, or configuring

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 How It Works gws does NOT 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 adds a new API endpoint or method, gws picks it up automatically — zero updates needed. Prerequisites Node.js 18+ — for npm install (or download a pre built binary from [GitHub Releases](https://github.com/googleworkspace/cli/releases)) A Google Cloud project — required for OAuth credentials. You can create one via the [Google Cloud Console](https://console.cloud.google.com/), with the [ gcloud CLI](https://cloud.google.com/sdk/docs/install), or with the gws auth setup command. A Google account with access to Google Workspace Installation Alternative installation methods: Quick Start 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 Quick Setup (recommended — requires gcloud CLI) Credentials are encrypted at rest (AES 256 GCM) with the key stored in your OS keyring. Scoped Login (for unverified/testing OAuth apps, limited to ~25 scopes) 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: Multiple Accounts Credentials are stored per account as credentials.<b64 email .enc in ~/.config/gws/ , with an accounts.json registry tracking defaults. Manual OAuth Setup (no gcloud) 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 — Type: Desktop app 5. 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: Headless / CI Service Account (server to server) Pre obtained Access Token Browser Assisted Auth (for AI agents) 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. 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. Command Structure The universal pattern for ALL gws commands: 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 Introspecting Schemas Core Services — Commands & Examples Google Drive Gmail Google Calendar Google Sheets Important: Sheets ranges use ! which bash interprets as history expansion. Always wrap values in single quotes. Google Docs Google Slides Google Chat Google Tasks Google Meet Google Forms Google Admin (Directory) Google Keep Google People (Contacts & Profiles) Google Workspace Events Google Vault (eDiscovery) Google Classroom Admin Reports (Audit Logs) Alert Center (Security Alerts) Cloud Identity Groups Settings Licensing Reseller Apps Script Workflow Helpers (Shortcut Commands) gws ships higher level helper commands for the most common multi step operations: Installing gws Skills Into Your Agent Project The gws repo ships 100+ SKILL.md files you can install directly into your agent's skills directory: <details <summary OpenClaw setup</summary 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. 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: 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: Full list: https://github.com/googleworkspace/cli/blob/main/docs/skills.md MCP Server Integration gws mcp starts a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio, exposing Google Workspace APIs as structured tools for any MCP compatible client. MCP Client Configuration VS Code / Copilot ( settings.json or .vscode/mcp.json ): Claude Desktop ( claude desktop config.json ): Cursor ( .cursor/mcp.json ): Gemini CLI Extension: 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. MCP Flags 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 Advanced Usage Dry Run (preview requests without executing) Pagination Piping

google-workspace-cli