Google Workspace CLI: An Agent-First Interface for the Google Workspace APIs

Google's gws is a command-line interface designed specifically for AI agents interacting with Google Workspace. Unlike traditional CLIs built around human usability, gws optimizes for what agents actually need: predictable, structured input and output, minimal token overhead, and an always-current command surface that reflects the live state of the API rather than static documentation.

The tool was created by Justin Poehnelt, a Senior Developer Relations Engineer at Google, who outlined the design philosophy in a blog post titled "You Need to Rewrite Your CLI for AI Agents." The core argument is that human developer experience and agent developer experience have different, often conflicting requirements, and most existing CLIs are built entirely for humans.

Human DX vs. agent DX

Traditional CLIs prioritize discoverability and forgiveness. They offer extensive --help menus, accept loose input, suggest corrections for typos, and expose configuration through many specific flags. For a person, this is intuitive. For an agent, it is expensive: the agent must learn which of dozens of possible flags applies to each command, and reasoning through that consumes tokens and introduces ambiguity.

Agents benefit from the opposite: predictability and structure. They do not need friendly flag names. They need to construct a valid request from a known schema, receive deterministic output, and move on. gws was built around this distinction from the start.

Key design decisions

JSON payloads instead of bespoke flags

Rather than exposing configuration through individual flags, gws accepts a single --json or --params flag containing a raw JSON payload that maps directly to the underlying API request body. Compare the two approaches for creating a spreadsheet:

A traditional human-first CLI might look like this:

some-cli sheets create --title "Q1 Budget" --locale "en_US" --sheet-title "January" --frozen-rows 1 --frozen-cols 2

The equivalent gws command:

gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget", "locale": "en_US"}, "sheets": [{"properties": {"title": "January", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2}}}]}'

For an agent, constructing one JSON object from an API schema is far simpler than selecting from a large set of flags. It also reduces the number of distinct things the agent needs to learn about the tool's interface.

Runtime schema introspection

Instead of consuming static documentation, an agent can query gws directly for the schema of any command using gws schema:

gws schema drive.about.get

This returns a full JSON schema describing the method signature, accepted parameters, request body structure, and response types. The agent gets exactly the information it needs to construct a valid call, without any documentation being pre-loaded into its context. This keeps token usage low and ensures the agent is always working from the current API definition rather than a potentially outdated reference.

Dynamically built command surface

gws does not ship with a hardcoded list of commands. Instead, it reads Google's API Discovery Service at runtime, which provides a machine-readable description of all available Google Workspace APIs.

When Google adds a new endpoint or modifies an existing one, gws picks up the change automatically. There is no lag between an API update and the CLI reflecting it, which means agents are always operating against the current API surface rather than a snapshot that may be months out of date.

Setting up gws

Getting gws running requires configuring OAuth credentials through the Google Cloud Platform. The steps below cover everything from installation to a verified login.

Prerequisites

Before starting, you need a Google account with access to a Google Cloud Platform (GCP) project, the gcloud CLI installed and initialized, and Node.js and npm available on your system.

Installing the CLIs

Install the gcloud CLI. On macOS with Homebrew:

brew install --cask google-cloud-sdk

For other operating systems, follow the official installation instructions. After installation, run gcloud init to initialize it.

Install the gws CLI globally via npm:

npm install -g @googleworkspace/cli

Running the authentication setup wizard

Start the interactive setup wizard:

gws auth setup

The wizard walks through five steps: verifying that gcloud is installed, selecting a Google account, selecting a GCP project, choosing which Workspace APIs to enable (Drive, Gmail, Sheets, Calendar, etc.), and then pausing to request an OAuth Client ID and Client Secret. Those credentials need to be generated in the GCP Console before the wizard can complete.

Creating OAuth 2.0 credentials in the GCP Console

In the GCP Console, navigate to APIs & Services > Credentials. Click + CREATE CREDENTIALS, select OAuth client ID, set Application type to Desktop app, give it a name such as gws-cli-creds, and click Create.

A dialog will appear containing a Client ID and a Client Secret.

Paste the Client ID into the waiting wizard prompt, press Enter, then paste the Client Secret and press Enter again. The wizard will then prompt you to run gws auth login to complete the flow, but there are two more GCP Console steps to handle first.

Configuring the redirect URI and test users

gws uses a local web server to receive the authentication token from Google. Run the login command to generate the authentication URL:

gws auth login

Do not open the URL yet. Find the redirect_uri parameter near the end of the URL. It will look something like redirect_uri=http://localhost:51065. Note the port number.

Back in the GCP Console, open the OAuth client ID you just created and add the full localhost address (e.g., http://localhost:51065) under Authorized redirect URIs, then click Save.

If your OAuth consent screen is in Testing mode (the default for new projects), navigate to APIs & Services > OAuth consent screen and add your Google email address under Test users. Without this, Google will block the authentication flow.

Once both changes are saved, copy the full URL that gws auth login generated, paste it into your browser, and complete the sign-in and permissions flow. Your terminal should display a JSON object with "status": "success". Verify the authenticated account with:

gws auth list

Working examples

Fetching recent emails

An agent asked to summarize the latest ten emails would run:

gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'

This returns a list of message IDs. The agent then fetches metadata for each one and presents a summary:

#: 1
From: Joules
Subject: Starts Today! Mid-Season Sale. Get up to 40% off!
Date: Fri 6 Mar, 09:58
Labels: Promotions, UNREAD

#: 2
From: Charles Aji (Substack)
Subject: Reducing the Cost of Your Intelligence
Date: Fri 6 Mar, 09:53
Labels: Updates, UNREAD
. . .

The entire operation requires a small number of API calls with no ambiguity in how to invoke them.

Creating a draft email in Gmail

The Gmail API requires messages to be formatted as MIME and base64-encoded before submission. An agent handling a request to draft a poem-based email would construct the encoded payload and pass it to gws:

gws gmail users drafts create --params '{"userId": "me"}' --json '{"message": {"raw": "<base64-encoded-mime-message>"}}'

The draft appears immediately in the Gmail drafts folder. The agent determines the correct command structure by querying gws schema gmail.users.drafts.create rather than consulting external documentation.

Building a Google Slides presentation

An agent tasked with creating a five-slide presentation with cat images would chain several gws commands. The first creates the blank presentation:

gws slides presentations create --json '{"title": "Claude Cats"}'

The response includes a presentationId. Subsequent calls to presentations.batchUpdate add text to the title slide and insert images into the remaining four slides, each call passing the presentationId as a parameter and the relevant request body as a JSON payload.

The agent discovers the correct structure for each batchUpdate request by querying the schema at runtime, keeping the entire operation self-contained within the CLI without needing pre-loaded API documentation.

Final thoughts

gws is a practical example of what it looks like to design tooling explicitly for AI agents rather than adapting human-facing tools after the fact. The combination of JSON-first input, runtime schema introspection, and a dynamically built command surface solves real problems: token overhead from static documentation, stale tooling that lags behind API changes, and the cognitive cost of translating natural language tasks into bespoke flag combinations.

The initial OAuth setup is the main friction point. Once that is behind you, the interface is consistent and the agent behavior is predictable. For anyone building agents that need to interact with Google Workspace, gws is worth the setup time.

The project is still early, and the GitHub repository is the best place to track its development and report issues.

Got an article suggestion? Let us know

Next article

Supermemory: Adding Long-Term Memory to AI Apps

Learn how to add persistent memory to AI applications using Supermemory's RAG architecture. Build a chatbot that remembers context across sessions.

→

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.