Google Workspace CLI

gws is a command-line tool for Google Workspace built for both developers and AI agents. Instead of shipping a fixed command list, it reads Google's Discovery Service at runtime and generates its entire command surface from Google's live API definitions. That means access to Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin APIs through one binary, with structured JSON output instead of hand-rolled curl calls against REST docs.

It's aimed at developers who script against Workspace APIs regularly, and at anyone building AI agents that need to read or write Workspace data without custom API wrappers. The project ships 100+ Agent Skill files and a Gemini CLI extension, so it also targets people building agent workflows on top of Gmail, Drive, Calendar, and Sheets.

Key features

• Dynamic command generation: commands are built from Google's Discovery Service at runtime, so new API endpoints and methods show up automatically without a CLI update.
• Structured JSON output: every response is JSON, making it straightforward to pipe into jq or feed to an LLM.
• Multiple auth flows: interactive OAuth login, manual OAuth setup, headless/CI credential export, service account auth, and pre-obtained access tokens, with credentials encrypted at rest using AES-256-GCM.
• Auto-pagination: --page-all streams paginated results as NDJSON, with configurable page limits and delay.
• Helper commands: hand-crafted shortcuts prefixed with + (like +send, +agenda, +standup-report) for common workflows that would otherwise take multiple raw API calls.
• AI agent skills: 100+ SKILL.md files covering every supported API plus curated recipes, installable via npx skills add or as a Gemini CLI extension.
• Schema introspection: gws schema <method> inspects request/response schemas for any Discovery method, and --dry-run previews requests before sending them.
• Model Armor integration: optional response sanitization to scan API responses for prompt injection before they reach an agent.

Ideal use cases

• Scripting Workspace operations (bulk file management in Drive, sending email via Gmail, updating spreadsheets) from shell scripts or CI pipelines without writing REST client code.
• Building an AI agent (via Gemini CLI or another framework) that needs structured, machine-readable access to Workspace data, using the included Agent Skills instead of custom tool definitions.
• Quick one-off Workspace API calls during debugging or exploration, using --help, --dry-run, and gws schema to understand a method before running it.
• Automating recurring workflows like standup reports, meeting prep, or weekly digests that pull from Calendar, Gmail, and Tasks together.

It's not a good fit if you need a polished GUI for non-technical users, or if you're looking for an officially supported Google product (the README states it explicitly is not). It also isn't suited for environments where you can't set up a Google Cloud project for OAuth credentials, since that's a hard prerequisite.

Installation

Prerequisites: Node.js 18+ (for npm install, unless using a pre-built binary), a Google Cloud project for OAuth credentials, and a Google account with Workspace access.

Recommended: download a pre-built binary from GitHub Releases and place it in your $PATH. Alternatively, install via npm:

npm install -g @googleworkspace/cli

Or build from source with Cargo:

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

Or use the Nix flake:

nix run github:googleworkspace/cli

Or install via Homebrew (macOS/Linux):

brew install googleworkspace-cli

After installing, set up authentication and try a command:

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