DEV Community

Cover image for How Can You and Use Google Workspace CLI
Wanda
Wanda

Posted on • Originally published at apidog.com

How Can You and Use Google Workspace CLI

#api #automation #cli #google

Google Workspace CLI (gws) is an open-source, dynamic command-line tool that provides unified access to Google Workspace APIs—including Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and more. Built directly from Google's live Discovery Service, gws commands are always up to date. Install globally via npm, authenticate once with OAuth, and connect directly to AI agents like Claude Code or Cursor using built-in skills. No boilerplate OAuth flows, no separate SDKs needed.

Try Apidog today

Why Use Google Workspace CLI?

Developers and admins often need to automate or query Google Workspace services—like managing Drive files, sending Gmail, creating Calendar events, appending to Sheets, editing Docs, or posting in Chat. Traditionally, this requires custom curl scripts, manual OAuth handling, pagination logic, or stitching together multiple SDKs.

Google Workspace APIs are powerful but fragmented, with each service having separate endpoints and nuances. This leads to boilerplate code that can break on API changes.

gws solves this by providing a single, Rust-powered CLI that dynamically discovers all Workspace API methods at runtime. You get instant access to new endpoints, outputs clean JSON, supports dry-runs, pagination helpers, and over 40 human-friendly shortcuts (e.g., gws gmail +send, gws calendar +agenda). It also ships with agent skills for Claude Code, Cursor, OpenClaw, and Gemini CLI—no custom definitions required.

For API testing and validation, pair gws with Apidog—a free API client for sending requests, inspecting responses, managing environments, and running test suites.

1. Install Google Workspace CLI

Prerequisite: Node.js 18 or later.

Check your Node version:

node --version
Enter fullscreen mode Exit fullscreen mode

Run Without Installing

Use npx for quick tests:

npx @googleworkspace/cli --help
npx @googleworkspace/cli drive files list --params '{"pageSize":1}'
Enter fullscreen mode Exit fullscreen mode

Global Install

For regular use, install globally:

npm install -g @googleworkspace/cli
gws --version
Enter fullscreen mode Exit fullscreen mode
  • Prebuilt binaries included (no Rust compilation needed).
  • Alternatively, download binaries from GitHub Releases, install via Homebrew (brew install googleworkspace/cli), or run via Nix.

2. Authenticate and Configure

Initial OAuth Setup

gws auth setup
Enter fullscreen mode Exit fullscreen mode
  • Launches a browser to create a Google Cloud project (if needed), enables APIs, and stores credentials securely in your OS keyring.

Install Agent Skills

npx skills add https://github.com/googleworkspace/cli
Enter fullscreen mode Exit fullscreen mode

Or run agent-specific installers if using Claude Code or Cursor. Restart your agent to auto-discover gws commands.

Project-Only Setup

gws auth setup --project
Enter fullscreen mode Exit fullscreen mode

Manage Authentication

  • Login or switch accounts:

    gws auth login

  • Check current user/scopes:

    gws auth whoami

  • Logout:

    gws auth logout

  • For CI/headless use:

    gws auth export --unmasked > creds.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json

  • Or re-use gcloud tokens:

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

Disable Telemetry

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

3. Using Core Commands

Google Workspace CLI discovers commands at runtime. Run gws --help to list available services.

Drive

  • List recent files:

    gws drive files list --params '{"pageSize":10, "q":"name contains report"}'

  • Upload file:

    gws drive +upload ./budget.xlsx --name "2026 Budget"

Gmail

  • Send email:

    gws gmail +send --to colleague@example.com --subject "Update" --body "See attached." --attach ./file.pdf

  • Reply or triage inbox:

    gws gmail +reply --message-id <ID> --body "Thanks!"
gws gmail +triage

Calendar

  • Create event:

    gws calendar +insert --summary "Sprint Planning" --start "2026-03-20T10:00" --end "2026-03-20T11:00" --attendees "team@example.com"

  • Show agenda:

    gws calendar +agenda --today

Sheets

  • Append row:

    gws sheets +append --spreadsheetId <ID> --range "Sheet1!A:C" --values "Task X,Done,2026-03-16"

Docs

  • Insert text:

    gws docs +write --documentId <ID> --text "New section added via Google Workspace CLI"

Chat

  • Post a message:

    gws chat +send --space <SPACE_ID> --text "Deployment complete 🚀"

Tips:

  • Use --dry-run to preview API calls.
  • Use --page-all for full pagination (NDJSON output).

4. Advanced Configuration

  • Persist settings:

    export GOOGLE_WORKSPACE_CLI_DEFAULT_PARAMS='{"prettyPrint":true}'

  • Adjust timeouts, output format (--json, --yaml), or force file-based keyring.

  • View current config:

    gws config

5. Integrating with AI Agents

Once skills are installed, agents (Claude Code, Cursor, etc.) can invoke gws natively.

  • Prompt pattern:

    "List my recent Drive files using Google Workspace CLI" or

    "Send a follow-up email via Google Workspace CLI"

  • Auto-invoke rule:

    Add to your agent's instructions (e.g., in CLAUDE.md):

    "Whenever the task involves Gmail, Drive, Calendar, Sheets, Docs, or Chat, use Google Workspace CLI commands automatically before responding. Resolve the service and method first."

Agents can return file paths or JSON results, keeping outputs clean and contextual.

6. API Testing with Apidog

Apidog is a free API client for sending requests, inspecting responses, managing environments (with OAuth tokens), and automating assertions.

Example Workflows:

  • Agent suggests appending to a Sheet → Test the exact Sheets.values.append payload in Apidog first.
  • Troubleshoot Gmail send scopes → Build and run the request visually.
  • Store service account keys or user tokens as variables → Switch accounts and validate.

Using Google Workspace CLI + Apidog gives you live API access and repeatable, validated test flows.

FAQ

Does Google Workspace CLI send my data externally?

No. All calls go directly to Google APIs. Your content never leaves your account.

Which services are supported?

All Workspace APIs discovered dynamically: Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, Script, and more.

How current are the commands?

gws queries the live Discovery Service; new methods appear automatically.

Does it require an API key?

Uses standard Google OAuth or service accounts—no separate key needed beyond auth credentials.

Which agents/editors are supported?

Claude Code, Cursor, OpenClaw, Gemini CLI, VS Code extensions—any MCP or Agent Skills-compatible tool.

What's the difference between raw commands and + helpers?

Raw = exact Discovery methods (e.g., drive.files.list).

  • helpers = shortcuts for common tasks (e.g., +upload, +send).

Can I use Google Workspace CLI without an AI agent?

Yes—it's perfect for scripts, automation, or daily terminal use.

Additional Resources

Top comments (0)