Google Workspace CLI for coding agents

When a coding agent has shell access, it can use Google Workspace CLI (gws) to send requests to the APIs for Google Drive, Gmail, Calendar, Sheets, Docs, Chat, and Google Admin. APIs are interfaces that let software request data or actions from these services. The CLI returns JSON, a text format with named fields and values. The agent can read specific fields and use them in later steps without parsing a human-oriented screen.

A useful first task is to list a few Drive files and return their names and types. The request reads data from Google Workspace and does not change any files. Check the current command help before relying on a command in an automated task. The official repository documents its supported APIs, setup, and command examples.

Install and authenticate

Install a supported version of Node.js before proceeding. With Node.js installed, install the package globally and check that the gws command is available:

npm install -g @googleworkspace/cli
gws --help

The official setup documentation covers authentication options. They include Google Cloud gcloud credentials and manual OAuth credentials. You can also use a previously obtained access token or service-account credentials. OAuth means granting the CLI permission to make API requests on behalf of a Google account. For OAuth, you need a Google Cloud project and credentials configured for the APIs you plan to call.

Complete authentication outside the agent prompt. Keep client secrets and access tokens in the credential configuration used by the CLI; do not paste them into instructions for the agent. The repository documents encrypted credential storage, but you still need to choose an authentication method that matches the account and access you intend the agent to use.

List Drive files

The following command asks Google Drive for up to five files that are not in the trash. It requests only each file’s ID, name, and MIME type, a label that identifies the file format:

gws drive files list --params '{"q":"trashed = false","pageSize":5,"fields":"files(id,name,mimeType)"}'

The command follows the repository’s documented pattern by starting with the API service. It then names a resource within that service and the method to run. Then pass the request settings, called API parameters, as JSON with --params. It makes a network request to Google Drive using the configured credentials. The response is JSON; this example does not need a separate --json flag. Check gws --help or the relevant command’s help for output-format options in the version you install. The repository says the CLI returns JSON by default and documents the current command syntax.

This is a read-only example. It does not create, edit, or delete Drive files. The results reflect the authenticated account’s access, so the command only returns files that account can see. The CLI documentation and your Google API access settings determine which Workspace services those credentials can use.

A coding agent could use this request to prepare a short inventory for a developer. For example, prompt it:

Use gws to list up to five non-trashed Drive files. Return each file’s name and type. Do not modify any files.

The agent can run the command, inspect the returned fields, and summarize them. No sample output is shown here because the results depend on the authenticated Drive account. These commands are based on the project documentation and have not been installed or tested for this article.

Use the bundled agent guidance

The repository also includes Agent Skills, which are instruction files that give an agent context for using a tool. The project documents skills for specific APIs and higher-level recipes, or instructions for common tasks, for services such as Gmail, Drive, Docs, Calendar, and Sheets. An agent can use those instructions alongside gws commands, while the CLI handles the API request and returns the result.

Because gws builds its command surface from Google’s Discovery Service, which publishes descriptions of Google APIs, its commands follow those descriptions. This gives the CLI a broad set of commands with a consistent structure. Before an agent runs a less familiar command, ask it to inspect the installed CLI’s help and explain the request it plans to send.