Google Workspace CLI Agent: Automate Docs and Sheets

Workspace CLI for Docs, Sheets, and Slides

The gws CLI treats every Workspace application as a namespace of commands. The pattern is consistent across all applications:gws [application] [resource] [operation] [flags]. This predictable structure means that once you understand how to list Drive files, you already understand how to list Docs documents, Sheets spreadsheets, or Calendar events — the pattern transfers across the entire CLI.

Every command returns structured JSON by default. This is deliberate — it makes gws composable with existing Unix toolchains. Pipe output to jq for filtering, feed it into Python for transformation, or pass it to shell scripts for further processing. The composability is what distinguishes gws from the Apps Script approach: every operation is a building block for larger pipelines rather than an isolated in-cloud function.

Installation and Credential Configuration

Installation requires a single npm command. The CLI is distributed as a pre-compiled binary wrapped in an npm package, so no Rust toolchain or compilation step is needed. After installation, you create a Google Cloud project, enable the required Workspace APIs, and configure OAuth credentials. The CLI handles the OAuth flow and stores credentials encrypted in your OS keyring.

Automating Google Docs with the CLI

Google Docs automation with gws covers three primary use cases: generating new documents from templates, reading document content for data extraction, and updating existing documents with new content. The template generation pattern is the most common for agency and operations workflows: maintain a master Docs template with named placeholders, then use the CLI to copy the template and replace placeholders with dynamic data on each execution.

For report generation workflows, the recommended pattern is to manage heavy formatting in the template itself and use the CLI only to insert dynamic content. Attempting to apply complex formatting through batchUpdate requests is verbose and error-prone. Templates handle the structure; the CLI handles the data. This separation of concerns also makes templates easier to update independently of automation scripts.

Sheets Data Pipelines via the CLI

Sheets is the most data-dense application in Workspace automation, and the gws CLI treats it accordingly. Beyond simple read and write operations, gws supports the git-like pull and push workflow that makes Sheets data a first-class participant in development pipelines: pull a spreadsheet as a local TSV file, transform it with any tool, and push changes back. This pattern enables version control, CI/CD integration, and bulk transformation workflows that are impossible with browser-based Sheets editing.

Slides Generation and Batch Automation

Batch presentation generation is one of the most time-consuming manual tasks in agency workflows — creating variations of a standard template for different clients, campaigns, or time periods. The gws slides commands make this scriptable: define a master template with named placeholders for text and images, maintain a Sheets spreadsheet with the variable data for each presentation, and run a script that iterates through the spreadsheet rows, copying the template and populating placeholders for each row.

MCP Server for AI Agent Orchestration

The most significant capability addition in gws is the built-in Model Context Protocol server that transforms the CLI into an AI agent toolkit. Instead of writing a script that calls specific gws commands in a predetermined sequence, you connect an AI agent to the MCP server and describe the desired outcome in natural language. The agent determines which gws tools to call, in what order, and with what parameters — adapting its approach based on the results of each step.

The practical workflow difference is significant. A scripted gws automation executes the same steps in the same order every time. An AI agent connected through MCP can adapt — if a template file is not found, it can search Drive for the latest version; if a spreadsheet row has missing data, it can skip or flag rather than error. This adaptability makes the MCP approach better for workflows with variable inputs, while scripted approaches remain better for high-volume, identical-operation automation where predictability is more important than flexibility.

Personas and Recipe Templates

Two gws features that significantly improve automation workflow ergonomics are personas and recipes. Personas address the multi-account problem. Recipes address the workflow reuse problem. Together, they transform a set of individual CLI commands into a structured automation library that scales across projects, clients, and team members.

The 40+ built-in recipes that ship with gws cover common business workflows including weekly team updates, client onboarding document generation, project status report compilation, and meeting recap distribution. Each built-in recipe can be inspected with gws recipe show [name] to understand its structure and use it as a template for custom recipes. The recipe format is declarative JSON, making it straightforward to version-control alongside your automation scripts.

Building Multi-Step Workflow Automations

The most valuable gws automations chain multiple Workspace applications together in workflows that would require significant API integration effort to build from scratch. The client monthly report workflow is a representative example: pull performance data from a Sheets dashboard, insert a formatted summary into a Docs report template, update a Slides executive summary deck with the headline numbers, and share both documents with the client via Drive. Each step is a gws command; the workflow is a shell script or recipe that sequences them.