Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@googleworkspace/cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

gws

One CLI for all of Google Workspace — built for humans and AI agents.
Drive, Gmail, Calendar, and every Workspace API. Zero boilerplate. Structured JSON output. 40+ agent skills included.

npm install -g @googleworkspace/cli

gws doesn't ship a static list of commands. It reads Google's own Discovery Service at runtime and builds its entire command surface dynamically. When Google Workspace adds an API endpoint or method, gws picks it up automatically.

[!IMPORTANT] This project is under active development. Expect breaking changes as we march toward v1.0.

Demo

Quick Start
Why gws?
Authentication
AI Agent Skills
Advanced Usage
Architecture
Development

Quick Start

npm install -g @googleworkspace/cli

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

Or build from source:

cargo install --path .

Why gws?

For humans — stop writing curl calls against REST docs. gws gives you tab‑completion, --help on every resource, --dry-run to preview requests, and auto‑pagination.

For AI agents — every response is structured JSON. Pair it with the included agent skills and your LLM can manage Workspace without custom tooling.

# List the 10 most recent files
gws drive files list --params '{"pageSize": 10}'

# Create a spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Send a Chat message
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Deploy complete."}' \
  --dry-run

# Introspect any method's request/response schema
gws schema drive.files.list

# Stream paginated results as NDJSON
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

Authentication

The CLI supports multiple auth workflows so it works on your laptop, in CI, and on a server.

Interactive (local desktop)

Credentials are encrypted at rest (AES-256-GCM) with the key stored in your OS keyring.

gws setup            # one-time: creates a Cloud project, enables APIs, logs you in
gws auth login       # subsequent logins

Requires the gcloud CLI to be installed and authenticated.

Headless / CI (export flow)

Complete interactive auth on a machine with a browser.

Export credentials:

gws auth export --unmasked > credentials.json

On the headless machine:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list   # just works

Service Account (server-to-server)

Point to your key file; no login needed.

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

For Domain-Wide Delegation, add:

export GOOGLE_WORKSPACE_CLI_IMPERSONATED_USER=admin@example.com

Pre-obtained Access Token

Useful when another tool (e.g. gcloud) already mints tokens for your environment.

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Precedence

Priority	Source	Set via
1	Access token	`GOOGLE_WORKSPACE_CLI_TOKEN`
2	Credentials file	`GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`
3	Encrypted credentials (OS keyring)	`gws auth login`
4	Plaintext credentials	`~/.config/gws/credentials.json`

Environment variables can also live in a .env file.

AI Agent Skills

The repo ships 40+ Agent Skills (SKILL.md files) — one for every supported API, plus higher-level helpers for common workflows like sending email, triaging a Gmail inbox, or subscribing to calendar events.

# Install all skills at once
npx skills add github:googleworkspace/cli

# Or pick only what you need
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

OpenClaw setup

# Symlink all skills (stays in sync with repo)
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

# Or copy specific skills
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

The gws-shared skill includes an install block so OpenClaw auto-installs the CLI via npm if gws isn't on PATH.

Advanced Usage

Multipart Uploads

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

Pagination

Flag	Description	Default
`--page-all`	Auto-paginate, one JSON line per page (NDJSON)	off
`--page-limit <N>`	Max pages to fetch	10
`--page-delay <MS>`	Delay between pages	100 ms

Model Armor (Response Sanitization)

Integrate Google Cloud Model Armor to scan API responses for prompt injection before they reach your agent.

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Variable	Description
`GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE`	Default Model Armor template
`GOOGLE_WORKSPACE_CLI_SANITIZE_MODE`	`warn` (default) or `block`

Architecture

gws uses a two-phase parsing strategy:

Read argv[1] to identify the service (e.g. drive)
Fetch the service's Discovery Document (cached 24 h)
Build a clap::Command tree from the document's resources and methods
Re-parse the remaining arguments
Authenticate, build the HTTP request, execute

All output — success, errors, download metadata — is structured JSON.

Development

cargo build                       # dev build
cargo clippy -- -D warnings       # lint
cargo test                        # unit tests
./scripts/coverage.sh             # HTML coverage report → target/llvm-cov/html/

License

Apache-2.0

Disclaimer

This is not an officially supported Google product.

@googleworkspace/cli