Automate Google Workspace from the command line with gws

Google Workspace CLI (gws) is an open-source command-line tool that provides unified access to Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and other Google Workspace APIs. It builds commands dynamically from Google’s Discovery Service, so you can automate Workspace tasks without maintaining separate SDKs, custom OAuth flows, or hand-written curl scripts.

Try Apidog today

Why use Google Workspace CLI?

Automating Google Workspace often requires you to:

• Configure OAuth scopes and credentials
• Learn separate APIs for each Workspace service
• Handle pagination manually
• Maintain multiple SDKs
• Update scripts when API methods change
• Define custom tools for AI agents

Google Workspace CLI provides a single, Rust-powered interface that discovers Workspace API methods at runtime. It was released in early 2026 by the Google team and announced by Addy Osmani.

The CLI provides:

• JSON output suitable for scripts and agents
• Dry-run support
• Pagination helpers
• Dynamically discovered API commands
• More than 40 task-oriented + helpers, such as gws gmail +send
• Agent skills for Claude Code, Cursor, OpenClaw, and Gemini CLI

If you also need to inspect requests, debug OAuth scopes, or verify payloads, Apidog can handle the API testing side of the workflow.

Install Google Workspace CLI

Google Workspace CLI requires Node.js 18 or later.

Check your installed version:

node --version

Run without installing

Use npx for a quick test or one-off script:

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

This downloads and runs the latest package without installing gws globally.

Install globally

For regular use, install the package globally:

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

The npm package includes prebuilt binaries, so you do not need to compile the Rust project locally.

You can also install the CLI from GitHub Releases, with Homebrew, or through Nix:

brew install googleworkspace/cli

Configure authentication

Run the guided setup:

gws auth setup

The setup flow opens a browser and handles:

1. Creating a Google Cloud project if needed
2. Enabling the required Workspace APIs
3. Completing the initial OAuth flow
4. Saving credentials in your operating system’s keyring

Stored credentials are encrypted with AES-256-GCM.

Configure only the current project

By default, setup applies globally. To create project-specific configuration, run:

gws auth setup --project

Check or change the authenticated account

Log in or switch accounts:

gws auth login

Inspect the current user and granted scopes:

gws auth whoami

Log out:

gws auth logout

Use Google Workspace CLI in CI or headless environments

Export credentials to a file:

gws auth export --unmasked > creds.json

Then point the CLI to that file:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json

Treat the exported file as a secret. Do not commit it to source control.

You can also reuse an access token from gcloud:

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

Disable telemetry

To disable anonymous usage collection:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1

Discover available commands

Google Workspace CLI discovers commands dynamically rather than relying on a fixed command list.

Start with:

gws --help

You can then explore the available services and methods from the command line.

Work with Google Drive

List files

List up to 10 files whose names contain report:

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

Because the output is JSON, you can pipe it into tools such as jq:

gws drive files list \
  --params '{"pageSize":10}' \
  | jq

Upload a file

Use the +upload helper to upload a local file:

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

Work with Gmail

Send an email

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

Reply to a message

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

Replace <ID> with the Gmail message ID.

Triage the inbox

gws gmail +triage

Work with Google Calendar

Create an event

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

Show today’s agenda

gws calendar +agenda --today

Work with Google Sheets

Append a row to a spreadsheet:

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

Replace <ID> with the spreadsheet ID from the Google Sheets URL.

Work with Google Docs

Insert text into a document:

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

Replace <ID> with the document ID.

Work with Google Chat

Post a message to a Chat space:

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

Replace <SPACE_ID> with the target Chat space ID.

Preview commands before executing them

Add --dry-run to preview the API call without executing it:

gws gmail +send \
  --to colleague@example.com \
  --subject "Update" \
  --body "See attached." \
  --dry-run

This is useful when:

• Testing commands generated by an AI agent
• Checking parameters before modifying Workspace data
• Debugging request payloads
• Reviewing automation in CI

Handle pagination

Use --page-all to retrieve all pages as newline-delimited JSON:

gws drive files list \
  --params '{"pageSize":100}' \
  --page-all

NDJSON output is convenient for streaming and processing large result sets.

Configure default behavior

Persist default parameters with an environment variable or a .env file:

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

The CLI also supports output options such as:

gws drive files list --params '{"pageSize":10}' --json

gws drive files list --params '{"pageSize":10}' --yaml

You can also adjust timeouts or force file-based keyring storage.

View the current configuration with:

gws config

Connect Google Workspace CLI to an AI coding agent

After authentication, install the bundled agent skills:

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

You can also use an agent-specific installer for tools such as Claude Code or Cursor. Restart the agent afterward so it can discover the installed skills.

Prompt the agent to use gws

Be explicit in your prompts:

List my recent Drive files using Google Workspace CLI.

Send a follow-up email via Google Workspace CLI.

Show today's Calendar agenda with gws, then summarize the meetings.

Add an automatic invocation rule

Add a rule like the following to CLAUDE.md, Cursor rules, or your agent’s instruction file:

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

This lets the agent use gws for Workspace operations and return file paths or JSON results without loading unnecessary data into its context.

Verify Workspace API calls with Apidog

Google Workspace CLI executes Workspace operations from the terminal. When you need to inspect a raw payload or troubleshoot authentication, use Apidog to reproduce and validate the underlying API request.

Practical workflows include:

• Test a Sheets.values.append payload before an agent writes to a spreadsheet
• Inspect Gmail send requests while debugging OAuth scopes
• Store user tokens or service-account credentials as environment variables
• Switch between accounts and compare responses
• Add assertions for repeatable API checks

A useful workflow is:

1. Build or preview the command with gws --dry-run.
2. Reproduce the request in Apidog.
3. Inspect the URL, headers, body, and response.
4. Confirm the required OAuth scopes.
5. Run the final gws command.
6. Save the API request as a repeatable test when appropriate.

Google Workspace CLI provides live Workspace access, while Apidog provides a visual environment for request inspection and repeatable API testing.

FAQ

Does Google Workspace CLI send my data externally?

No. Calls go directly to Google APIs, and your content remains in your Google account.

Which services does Google Workspace CLI support?

It supports Workspace APIs discovered dynamically, including Drive, Gmail, Calendar, Sheets, Docs, Chat, Admin, and Script.

How current are the commands?

Google Workspace CLI queries Google’s live Discovery Service, so newly exposed methods can appear without waiting for a CLI update.

Does it require an API key?

It uses standard Google OAuth or service-account authentication. You do not need a separate API key beyond the required authentication credentials.

Which agents and editors does it support?

Google Workspace CLI can be used with Claude Code, Cursor, OpenClaw, Gemini CLI, VS Code extensions, and tools compatible with MCP or Agent Skills.

What is the difference between raw commands and + helpers?

Raw commands map to Discovery API methods, such as drive.files.list.

Commands prefixed with + are shortcuts for common tasks, such as:

gws drive +upload
gws gmail +send
gws calendar +agenda

Can I use Google Workspace CLI without an AI agent?

Yes. You can use it directly for shell scripts, CI jobs, scheduled automation, and day-to-day terminal tasks.

Additional resources

• Google Workspace CLI GitHub repository → https://github.com/googleworkspace/cli
• Full README and documentation → https://github.com/googleworkspace/cli/blob/main/README.md
• Agent skills folder → https://github.com/googleworkspace/cli/tree/main/skills
• Google Workspace API reference → https://developers.google.com/workspace
• Quotas dashboard → https://console.cloud.google.com/apis/api
• Apidog free API client → https://apidog.com?utm_source=dev.to&utm_medium=wanda&utm_content=blog-sync