# gws (Google Workspace CLI)

> One command-line tool for every Google Workspace API, with JSON output agents can parse

- Category: Agents & Automation / Workflow Automation
- Language: Rust
- Licence: Apache-2.0
- Repository: https://github.com/googleworkspace/cli
- Website: https://developers.google.com/workspace
- Canonical page: https://ai-tldr.dev/tools/google-workspace-cli/

## In short

gws (Google Workspace CLI) is One command-line tool for every Google Workspace API, with JSON output agents can parse. Its distinguishing trick is that it ships no static command list. It sits in the Workflow Automation category of the Agents & Automation tools and is open-source, written in Rust and licensed Apache-2.0.

## Overview

gws is a single command-line tool that covers Google Workspace: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin and the rest. Its distinguishing trick is that it ships no static command list. At runtime it reads Google's own Discovery Service and builds its entire command surface from the API descriptions, so when Workspace adds an endpoint or a method, gws picks it up without waiting for a release.

Everything comes back as structured JSON, which is what makes it useful on the agent side of the house as well as the human side. The repository bundles 40+ agent skills, so an LLM-driven assistant can manage Workspace through the CLI instead of needing bespoke tool definitions per API. For humans there is `--help` on every resource, `--dry-run` to preview a request before it fires, and automatic pagination.

The project is published under the googleworkspace GitHub organisation and licensed Apache 2.0, but its README states plainly that it is not an officially supported Google product and that it is under active development with breaking changes expected before v1.0. Authentication uses OAuth against a Google Cloud project you own; `gws auth setup` walks through creating the credentials.

## What it does

- Command surface built dynamically from Google's Discovery Service — new API methods appear automatically
- Covers Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin and the other Workspace APIs from one binary
- Structured JSON responses on every command, so agents and scripts can parse the output
- 40+ bundled AI agent skills for LLM-driven Workspace automation
- `--help` on every resource, `--dry-run` request previews and auto-pagination
- Installs as a prebuilt binary, via npm, Homebrew, Nix or `cargo install`

## Getting started

You need Node.js 18+ for the npm route, a Google Cloud project for OAuth credentials, and a Google account with Workspace access. All commands below come from the project README.

1. Install the CLI

   The recommended route is the prebuilt binary from GitHub Releases; npm automates downloading the right one for your platform.

```bash
npm install -g @googleworkspace/cli
```

2. Or install it another way

   Homebrew on macOS and Linux, a Nix flake, or a build from source.

```bash
brew install googleworkspace-cli
nix run github:googleworkspace/cli
cargo install --git https://github.com/googleworkspace/cli --locked
```

3. Set up credentials and sign in

   `auth setup` walks through the Google Cloud project configuration; `auth login` handles subsequent OAuth logins.

```bash
gws auth setup
gws auth login
```

4. Make your first call

   Request parameters go in `--params` as JSON; the response comes back as JSON too.

```bash
gws drive files list --params '{"pageSize": 5}'
```

5. Write as well as read

   Request bodies go in `--json`. Add `--dry-run` to see exactly what would be sent without sending it.

```bash
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run
```

## When to use it

- Reach for it when an agent needs to act on Drive, Gmail or Calendar and you would rather not write a tool wrapper per API
- Reach for it to script Workspace admin chores with JSON in and JSON out
- Reach for it when a Workspace API method is too new for the client library you are using
- Reach for it to preview a destructive Workspace call with `--dry-run` before running it for real