Skip to main content
hc
Submit
toolsSource-backedReview first Safety ✓ Privacy ✓

Google Workspace CLI

Apache-2.0 `gws` command-line tool for Google Workspace APIs with structured JSON output, dynamic Discovery API commands, npm and release installers, Gemini CLI extension metadata, and 100+ bundled Agent Skills.

by Google Workspace CLI Contributors·added 2026-06-18·
CLI
HarnessCLI
Review first — review before installing

Open the source and read safety notes before installing.

Safety notes

  • `gws` can read, create, update, send, delete, share, upload, export, and administer Google Workspace resources depending on OAuth scopes and the command used.
  • Require user confirmation before agent-initiated Gmail sends, Drive sharing, Calendar changes, Admin SDK actions, Apps Script pushes, file uploads, or destructive operations.
  • Use `--dry-run` for write workflows when supported, and keep OAuth scopes narrow instead of granting broad Workspace access for convenience.
  • The npm package runs a postinstall script that downloads a platform-specific binary from GitHub Releases and verifies the published SHA256 checksum before extracting it.
  • Model Armor sanitization can screen API responses before they reach an agent, but it may send prompt or response content to the configured Google Cloud Model Armor template.
  • The README says this project is under active development and not an officially supported Google product; expect breaking changes before v1.0.

Privacy notes

  • `gws` can expose emails, attachments, files, folders, shared drives, calendars, contacts, Chat spaces, Docs, Sheets, Slides, Forms, Keep notes, Meet data, Tasks, Classroom data, Apps Script projects, Admin reports, and audit logs.
  • Interactive credentials are encrypted at rest with a key stored in the OS keyring, with a file-key fallback when configured; exported credentials and service-account JSON files are highly sensitive.
  • `GOOGLE_WORKSPACE_CLI_TOKEN` has highest precedence when set; avoid leaking access tokens through shell history, `.env` files, CI logs, support messages, screenshots, or agent prompts.
  • Structured JSON, NDJSON pagination, downloads, `--output` files, log files, and model-visible command output can contain personal, customer, regulated, or confidential Workspace data.
  • Agent skills installed from the repository teach agents how to call `gws`; the data exposure risk is controlled by the authenticated account, scopes, local files, and command approvals.

Prerequisites

  • Node.js 18 or newer for the npm installer, or a platform-specific prebuilt binary from GitHub Releases.
  • A Google Cloud project and OAuth configuration, either created through `gws auth setup` or configured manually in Google Cloud Console.
  • A Google account or Google Workspace account with access to the target Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Classroom, Meet, or other APIs.
  • Explicit scope selection for the APIs the agent may use; unverified OAuth apps in testing mode cannot request the full recommended scope set.
  • A review boundary for agent write/delete actions, exported credentials, service-account keys, JSON outputs, logs, and downloaded files.

Schema details

Install type
cli
Troubleshooting
No
Source repository stats
Scope
Source repo
Collection metadata
Estimated setup
30 minutes
Difficulty
advanced
Tool listing metadata
Pricing
free
Disclosure
editorial
Application category
DeveloperApplication
Operating system
macOS, Windows, Linux
Full copyable content
npm install -g @googleworkspace/cli
gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'
gws schema drive.files.list

npx skills add https://github.com/googleworkspace/cli

About this resource

Overview

Google Workspace CLI, exposed as gws, is an Apache-2.0 command-line tool for operating Google Workspace APIs from a terminal or AI agent. The repository describes it as one CLI for Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and the wider Workspace API surface, with structured JSON output and commands generated dynamically from Google's Discovery Service.

For agent workflows, the repo ships a large Agent Skills library, a shared gws skill, service-specific skills, helper skills, persona bundles, recipes, and Gemini CLI extension metadata. That makes it a practical bridge between LLM agents and real Google Workspace operations without writing one-off REST wrappers for every Gmail, Drive, Calendar, Sheets, or Admin SDK task.

Install

Install through npm:

npm install -g @googleworkspace/cli
gws auth setup
gws auth login
gws drive files list --params '{"pageSize": 5}'

The README also documents platform-specific binaries from GitHub Releases, Homebrew on macOS/Linux, cargo install from source, and Nix.

Install all bundled Agent Skills:

npx skills add https://github.com/googleworkspace/cli

Or install only a focused subset:

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

The README also documents OpenClaw setup by symlinking or copying the skills/gws-* folders into an OpenClaw skills directory, and Gemini CLI setup through:

gemini extensions install https://github.com/googleworkspace/cli

Capabilities

Area Google Workspace CLI Coverage
API surface Dynamically builds commands from Google Discovery documents, covering Workspace APIs as they are discovered
Core services Drive, Gmail, Calendar, Sheets, Docs, Slides, Chat, Admin SDK, Tasks, People, Forms, Keep, Meet, Classroom, Apps Script, Workspace Events, and Model Armor
Agent output Structured JSON by default, with schema introspection, NDJSON pagination, binary output support, and predictable exit codes
Helpers Hand-crafted + commands for Gmail send/reply/triage/watch, Sheets read/append, Docs write, Drive upload, Calendar agenda/insert, Chat send, Apps Script push, workflow summaries, and Model Armor sanitization
Agent Skills 100+ SKILL.md files covering services, helpers, personas, and recipes for common Gmail, Drive, Docs, Sheets, Calendar, Chat, and Admin workflows
Authentication Browser OAuth, gws auth setup, OAuth credentials files, service-account JSON, pre-obtained access tokens, encrypted local credentials, and .env support
Install paths npm package, GitHub release binaries with SHA256 checks, Homebrew, Cargo, and Nix
Agent hosts Skills install path via npx skills, documented OpenClaw copy/symlink setup, and Gemini CLI extension metadata

Use Cases

  • Give an agent structured, JSON-first access to Gmail, Drive, Calendar, Docs, Sheets, Chat, and Admin SDK tasks.
  • Use the bundled skills as reusable workflows for Claude-style skill runners, OpenClaw, Gemini CLI, and other agent hosts that can consume skill folders.
  • Build a Workspace operations assistant for inbox triage, Drive organization, meeting prep, weekly summaries, file announcements, doc generation, and task creation.
  • Run admin or audit workflows against Workspace APIs while keeping command outputs machine-readable.
  • Use Model Armor sanitization for prompt or response review before sensitive Workspace content reaches an agent.

Source Review

Verified on 2026-06-18:

  • GitHub metadata reported googleworkspace/cli as an Apache-2.0 Rust repository with topics including google-workspace, agent-skills, ai-agent, automation, cli, discovery-api, google-admin, google-calendar, google-chat, google-docs, google-drive, google-sheets, oauth2, and gemini-cli-extension.
  • The README describes gws as a CLI for Google Workspace built for humans and AI agents, with structured JSON output, dynamic Discovery Service command generation, and 40+ agent skills in its opening summary.
  • The README states that the repo ships 100+ Agent Skills, including service-specific skills, higher-level helpers, and curated recipes for Gmail, Drive, Docs, Calendar, and Sheets.
  • docs/skills.md lists service skills, helper skills, persona skills, and recipe skills for Workspace APIs and cross-service workflows.
  • The README documents npm, GitHub release binary, Cargo, Nix, and Homebrew installation paths, plus gws auth setup, gws auth login, OAuth token, credentials-file, and service-account authentication modes.
  • The README documents Gemini CLI extension installation and OpenClaw setup for the bundled skills/gws-* folders.
  • The README documents helper commands, pagination, --dry-run, schema introspection, structured exit codes, and Model Armor response sanitization.
  • .env.example documents token, credentials file, OAuth client, config directory, Model Armor, sanitize mode, and project ID environment variables.
  • skills/gws-shared/SKILL.md declares a shared Agent Skill requiring the gws binary and documenting global flags, dry-run, sanitize, output, upload, pagination, and security rules for agents.
  • npm/install.js downloads the matching GitHub Release artifact, downloads the .sha256 file, verifies the SHA256 checksum, extracts the binary, and writes the installed version marker.
  • package.json and npm registry metadata report npm package @googleworkspace/cli version 0.22.5, Apache-2.0 license, Node.js 18+ engine, gws binary, npm postinstall, supported platform artifacts, and provenance attestation metadata.
  • The latest GitHub release was v0.22.5, published on 2026-03-31, with macOS, Linux, and Windows artifacts plus checksum files.
  • The README states that the project is under active development, expects breaking changes before v1.0, and is not an officially supported Google product.

Safety and Privacy

gws is powerful because it can operate a real Google account or Workspace tenant. Treat every authenticated command as account access. Start with narrow OAuth scopes, prefer read-only operations while testing, use --dry-run before writes where available, and require confirmation before sending email, sharing files, modifying calendars, changing admin state, pushing Apps Script code, or deleting data.

Agent usage increases the risk because model-visible output can include private email, documents, spreadsheets, contacts, calendars, chat messages, attachments, audit events, or admin records. Keep credentials out of prompts and logs, avoid exporting broad credential files unless needed, and scope each agent task to the minimum Workspace services required.

Duplicate Check

Checked current content/tools/, content/mcp/, content/agents/, content/skills/, guides, README entries, open pull requests, and repository-wide content for Google Workspace CLI, googleworkspace/cli, @googleworkspace/cli, gws, Google Workspace Agent Skills, Gemini CLI Google Workspace extension, and matching source URLs. No dedicated Google Workspace CLI entry, exact source URL duplicate, target file, or open duplicate PR was found.

Disclosure

Editorial listing. No paid placement or affiliate link is used. The project is Apache-2.0 open-source software from the googleworkspace/cli repository and explicitly says it is not an officially supported Google product. Google Workspace, Google Cloud, OAuth apps, Model Armor, npm, Homebrew, GitHub Releases, Nix, Gemini CLI, OpenClaw, and third-party agent hosts may have separate licenses, billing, terms, quotas, privacy controls, and operational requirements.

#google-workspace#gws#agent-skills#gmail#drive#sheets#calendar#gemini-cli

Source citations

Add this badge to your README

Show that Google Workspace CLI is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

Listed on HeyClaude
[![Listed on HeyClaude](https://heyclau.de/badge/tools/google-workspace-cli.svg)](https://heyclau.de/entry/tools/google-workspace-cli)

How it compares

Google Workspace CLI side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

FieldGoogle Workspace CLI

Apache-2.0 `gws` command-line tool for Google Workspace APIs with structured JSON output, dynamic Discovery API commands, npm and release installers, Gemini CLI extension metadata, and 100+ bundled Agent Skills.

Open dossier 		ClawHub

MIT-licensed OpenClaw skill and plugin registry with a hosted catalog, `clawhub` CLI, npm package, native OpenClaw install flows, SKILL.md publishing, plugin package publishing, vector search, scan status, moderation controls, install lockfiles, and opt-out install telemetry.

Open dossier 		Gemini CLI

Google's open-source terminal AI agent for Gemini-powered coding and automation, with code understanding, file edits, shell commands, web fetching, Google Search grounding, MCP server integrations, checkpointing, GEMINI.md context files, and GitHub workflow automation.

Open dossier 		Skills CLI

MIT-licensed `skills` CLI from Vercel Labs for installing, using, finding, listing, updating, removing, and initializing Agent Skills across Claude Code, Codex, Cursor, OpenCode, OpenClaw, Gemini CLI, GitHub Copilot, Windsurf, Zed, and dozens of other agent hosts.

Open dossier
Trust
Install riskReview firstReview firstReview firstReview first
Notes Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓ Safety ✓ Privacy ✓
Categorytoolstoolstoolstools
Sourcesource-backedsource-backedsource-backedsource-backed
AuthorGoogle Workspace CLI ContributorsOpenClawGoogleVercel Labs
Added2026-06-182026-06-182026-06-182026-06-18
Platforms
CLI
CLI
GeminiCLI
CursorCodexCLI
Source repo————
Safety notes✓`gws` can read, create, update, send, delete, share, upload, export, and administer Google Workspace resources depending on OAuth scopes and the command used. Require user confirmation before agent-initiated Gmail sends, Drive sharing, Calendar changes, Admin SDK actions, Apps Script pushes, file uploads, or destructive operations. Use `--dry-run` for write workflows when supported, and keep OAuth scopes narrow instead of granting broad Workspace access for convenience. The npm package runs a postinstall script that downloads a platform-specific binary from GitHub Releases and verifies the published SHA256 checksum before extracting it. Model Armor sanitization can screen API responses before they reach an agent, but it may send prompt or response content to the configured Google Cloud Model Armor template. The README says this project is under active development and not an officially supported Google product; expect breaking changes before v1.0.✓ClawHub installs agent skills and OpenClaw plugins. Inspect source links, files, changelogs, declared runtime metadata, scan state, and plugin compatibility before installing or updating. `clawhub install`, `openclaw skills install`, and update commands write local skill files and metadata such as `.clawhub/lock.json` and per-skill origin records. Pin important local installs before updating shared workspaces. `clawhub token` prints the stored API token to stdout. Avoid exposing tokens through shell history, CI logs, support transcripts, screenshots, or model prompts. Publishing a skill to ClawHub releases it under MIT-0 according to the skill-format docs; do not publish proprietary, private, customer, or conflicting-license content. Plugin publishing resolves local folders, GitHub repositories, GitHub refs, or archives and checks OpenClaw compatibility metadata. Use `--dry-run`, verify artifacts, and review ClawPack digest/scan output before public release. Scan-held or blocked releases can be hidden from public catalog and install surfaces while remaining visible to owners; do not assume search visibility proves a release is safe or accepted.✓Gemini CLI can read and edit local files, run shell commands, fetch web content, use Google Search grounding, and call configured MCP servers; keep it inside version-controlled workspaces and review high-impact actions. MCP integrations can expose databases, SaaS accounts, browsers, cloud resources, files, or internal APIs to the agent; apply least privilege and approval gates per server. Preview and nightly release channels may contain regressions or unvetted changes; use stable releases for shared or production workflows unless testing intentionally. Non-interactive scripting can run without the same operator attention as an interactive session; constrain prompts, output parsing, credentials, and command permissions. GitHub workflow automation through Gemini CLI should be reviewed like any other code-review or issue-triage automation before granting repository permissions.✓Agent Skills are executable instructions for coding agents. Inspect `SKILL.md` and supporting files before installing or using skills from unknown repositories. `skills add`, `skills update`, `skills remove`, and `experimental_sync` can write, replace, symlink, copy, or remove skill folders across many local agent directories. Review `--agent`, `--skill`, `--all`, `--global`, and `--yes` flags before running broad operations. `skills use` can materialize a skill into a temporary directory and print the generated prompt, or start a supported agent interactively with that prompt. Treat untrusted skill text as prompt-bearing code. Symlink install mode keeps a canonical copy and links agent directories to it. Copy mode creates independent copies. Choose deliberately when working across shared repos, Windows environments, containers, or synchronized directories. The CLI includes explicit warnings for OpenClaw community skills in `skills use`; do not bypass those warnings unless you understand the trust model for the selected source. The security audit lookup is best-effort and never blocks installation. A missing or safe-looking audit result is not a substitute for reviewing the skill source.
Privacy notes✓`gws` can expose emails, attachments, files, folders, shared drives, calendars, contacts, Chat spaces, Docs, Sheets, Slides, Forms, Keep notes, Meet data, Tasks, Classroom data, Apps Script projects, Admin reports, and audit logs. Interactive credentials are encrypted at rest with a key stored in the OS keyring, with a file-key fallback when configured; exported credentials and service-account JSON files are highly sensitive. `GOOGLE_WORKSPACE_CLI_TOKEN` has highest precedence when set; avoid leaking access tokens through shell history, `.env` files, CI logs, support messages, screenshots, or agent prompts. Structured JSON, NDJSON pagination, downloads, `--output` files, log files, and model-visible command output can contain personal, customer, regulated, or confidential Workspace data. Agent skills installed from the repository teach agents how to call `gws`; the data exposure risk is controlled by the authenticated account, scopes, local files, and command approvals.✓The CLI stores API token and registry configuration in the operating-system config directory or the path set by `CLAWHUB_CONFIG_PATH`. Logged-in `clawhub install` may send best-effort install telemetry containing the skill slug and version only; set `CLAWHUB_DISABLE_TELEMETRY=1` to opt out. ClawHub public listings can expose skill files, source links, versions, changelogs, install counts, stars, comments, publisher identity, and scan summaries. Publishing uploads `SKILL.md` plus supporting text files to the hosted registry. Keep secrets, private prompts, customer data, proprietary code, and credentials out of published bundles. Self-hosting ClawHub involves Convex, GitHub OAuth, JWT/JWKS keys, OpenAI embeddings for vector search, file storage, moderation data, and report handling.✓Prompts, selected source files, GEMINI.md context, shell output, web fetches, MCP tool arguments, MCP tool results, checkpoints, and command output may be sent through the configured Gemini or Vertex AI route. Keep API keys, Google Cloud project IDs, service credentials, private paths, customer data, and internal code out of prompts, logs, shared terminal output, and public issues. Google account, Gemini API, Vertex AI, retention, quota, telemetry, and billing behavior depend on the selected authentication mode and organizational settings. MCP server logs, Gemini CLI logs, terminal history, GitHub workflow logs, and generated artifacts can retain sensitive code or operational context.✓By default, the CLI can send telemetry to `add-skill.vercel.sh` unless `DISABLE_TELEMETRY` or `DO_NOT_TRACK` is set. Telemetry fields in source include CLI version, CI flag, detected agent name, event type, source, selected skills, selected agents, global flag, source type, update counts, find query, and result counts. Security-audit lookup requests can send the skill source and selected skill slugs to the audit endpoint. Local project and global installs can persist source names, selected skills, agent targets, canonical paths, lock data, symlinks, and copied skill contents on disk. Skill contents used through `skills use` are embedded into the generated prompt and may be sent to the downstream model provider or interactive agent process.
Prerequisites
  • Node.js 18 or newer for the npm installer, or a platform-specific prebuilt binary from GitHub Releases.
  • A Google Cloud project and OAuth configuration, either created through `gws auth setup` or configured manually in Google Cloud Console.
  • A Google account or Google Workspace account with access to the target Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Classroom, Meet, or other APIs.
  • Explicit scope selection for the APIs the agent may use; unverified OAuth apps in testing mode cannot request the full recommended scope set.
  • Node.js 22 or newer for the published `clawhub` npm CLI.
  • OpenClaw installed and configured when using native `openclaw skills` or `openclaw plugins` install/update commands.
  • A GitHub-backed ClawHub account or API token for publishing, delete/undelete, scan, and other authenticated registry workflows.
  • A valid skill folder with `SKILL.md` when publishing skills, or an OpenClaw-compatible plugin package/source when publishing plugins.
  • Node.js 20 or newer for the npm package, or a supported Homebrew, MacPorts, or Conda install path.
  • A Google account, Gemini API key, or Vertex AI configuration for the selected authentication route.
  • A project workspace where file access, shell commands, web fetching, and MCP server access are intentionally scoped.
  • A decision on stable, preview, or nightly release channels before using the CLI in team workflows.
  • Node.js 18 or newer for the published `skills` npm package.
  • At least one supported agent host installed if using auto-detected targets, such as Claude Code, Codex, Cursor, OpenCode, OpenClaw, Gemini CLI, GitHub Copilot, Windsurf, Zed, or another supported agent.
  • A reviewed skill source from GitHub, GitLab, a git URL, a local path, a direct skill folder, or another supported provider.
  • A decision between project-scoped skills that live under the current repository and global skills that live under the user's home/config directories.
Install
npm install -g @googleworkspace/cli
npm install -g clawhub
npm install -g @google/gemini-cli
npm install -g skills
Config
{
  "auth": {
    "interactive": "gws auth setup && gws auth login",
    "credentialsFileEnv": "GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE",
    "tokenEnv": "GOOGLE_WORKSPACE_CLI_TOKEN"
  },
  "agentSkills": {
    "all": "npx skills add https://github.com/googleworkspace/cli",
    "drive": "npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive",
    "gmail": "npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail"
  },
  "safety": {
    "previewWrites": "Use --dry-run before write or delete workflows",
    "sanitize": "Use --sanitize or GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE when Model Armor review is required"
  }
}
{
  "openclawSkills": {
    "search": "openclaw skills search \"calendar\"",
    "install": "openclaw skills install @openclaw/demo",
    "update": "openclaw skills update --all"
  },
  "openclawPlugins": {
    "search": "openclaw plugins search \"calendar\"",
    "install": "openclaw plugins install clawhub:<package>",
    "update": "openclaw plugins update --all"
  },
  "clawhubCli": {
    "login": "clawhub login",
    "publishSkill": "clawhub skill publish ./my-skill --dry-run",
    "publishPlugin": "clawhub package publish <source> --family code-plugin --dry-run"
  }
}
—
{
  "projectInstall": "npx skills add vercel-labs/agent-skills --skill frontend-design -a claude-code",
  "globalInstall": "npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y",
  "temporaryUse": "npx skills use vercel-labs/agent-skills@web-design-guidelines | claude",
  "disableTelemetry": "DISABLE_TELEMETRY=1 npx skills list"
}
Citations
ClaimUnclaimedUnclaimedUnclaimedUnclaimed

Signals

Loading live community signals…

More like this, weekly

A short, calm digest of reviewed Claude resources. Unsubscribe any time.