cli

Purpose

Google Workspace CLI (command name gws) is a community-built unofficial command-line tool designed to provide a single command-line entry point for Google Workspace, giving unified access to all Workspace APIs including Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. It is designed for human users and AI agents, to simplify REST API calls, automate workflows, and support AI agent integration.

Main capabilities

• Dynamic command construction: It does not provide a static command list, but instead reads the Google Discovery Service at runtime to dynamically build the entire command surface. When Google Workspace adds new API endpoints or methods,gws automatically recognizes them.
• Structured JSON output: All responses (success, error, download metadata) are structured JSON, making them easy for scripts to parse and for AI agents to use.
• AI Agent Skills: The repository includes 100+ Agent Skills (SKILL.md files), covering every supported API, as well as advanced assistants for common workflows and 50 curated recipes (Gmail, Drive, Docs, Calendar, Sheets).
• Multiple authentication methods: Supports interactive (local desktop), headless/CI (export flow), service account (server-to-server), and prefetched access token. Credentials are encrypted at rest (AES-256-GCM), with keys stored in the OS keyring.
• Helper commands: Some services provide hand-written helper commands, distinguished by the + prefix (such as +agenda、+standup-report、+weekly-digest、+meeting-prep), automatically using the Google account time zone.
• Model protection (response sanitization): Can integrate Google Cloud Model Armor to scan API responses for prompt injection before they reach the agent.
• Structured exit codes: Scripts can branch based on failure type without parsing error output.

Usage

Installation

• Recommended: Download the prebuilt binary for your operating system and architecture from GitHub Releases, extract it, and place gws into $PATH.
• npm (requires Node.js 18+):npm install -g @googleworkspace/cli(automatically downloads the corresponding binary).
• Build from source, Nix flake (github:googleworkspace/cli), Homebrew (macOS and Linux).

Authentication setup

• Interactive (local desktop): Run gws auth setup(requires gcloud CLI) or manually configure OAuth in the Google Cloud Console. Unverified apps (test mode) are limited to about 25 scopes; the recommended preset includes 85+ scopes and will fail, so you need to select individual services to filter scopes.
• Manual OAuth setup: Create an OAuth client in the Google Cloud Console (type: Desktop app), download the JSON and save it to ~/.config/gws/client_secret.json, and add test users.
• Browser-assisted authentication: A human runs gws auth login to open the URL and approve; the agent can assist by opening the URL and handling consent prompts.
• Headless/CI: Complete interactive authentication on a machine with a browser, export credentials gws auth export --unmasked > credentials.json, and set the GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE environment variable on the headless machine.
• Service account: Point to the key file, no login required.
• Prefetched access token: Suitable for environments where another tool has already generated a token.

Basic usage

• Humans:gws provides --help、--dry-run for each resource, preview the request, and automatically paginate.
• AI agents: All responses are structured JSON, and together with Agent Skills, LLMs can manage Workspace without custom tools.
• Gemini CLI extension: First gws auth setup authenticate the CLI, then gemini extensions install https://github.com/googleworkspace/cli, and the Gemini CLI agent can directly access all gws commands and Workspace Agent Skills.

Use Cases

• Automation scripts: replace curl calls to REST documentation, simplifying Google Workspace operations.
• AI agent integration: provide LLMs with a structured tool interface to manage Drive, Gmail, Calendar, etc.
• Server-side/CI environments: enable headless operations via service accounts or exported credentials.
• Common workflows: use helper commands to quickly generate agendas, standup reports, etc.

Limitations

• Unofficial product: explicitly states "this is not an officially supported Google product."
• Under active development: the project is moving toward v1.0, and breaking changes are expected.
• Authentication limitations: unverified OAuth apps (testing mode) are limited to about 25 scopes; test users must be added manually, otherwise an "Access blocked" error occurs.
• Environment requirements: npm installation requires Node.js 18+;gws auth setup requires the gcloud CLI (or manual setup).
• API not enabled: if the required API is not enabled in the GCP project, a 403 accessNotConfigured error is returned, and it must be enabled manually or by running gws auth setup.
• Sheets range escaping: when ranges use ! , they must be wrapped in single quotes to avoid bash history expansion.
• Other: redirect_uri_mismatch requires ensuring the OAuth client type is Desktop app.