DEV Community

Preecha
Preecha

Posted on

How Can You and Use Google Workspace CLI

#api #automation #cli #opensource

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
Enter fullscreen mode Exit fullscreen mode

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}'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Configure authentication

Run the guided setup:

gws auth setup
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Check or change the authenticated account

Log in or switch accounts:

gws auth login
Enter fullscreen mode Exit fullscreen mode

Inspect the current user and granted scopes:

gws auth whoami
Enter fullscreen mode Exit fullscreen mode

Log out:

gws auth logout
Enter fullscreen mode Exit fullscreen mode

Use Google Workspace CLI in CI or headless environments

Export credentials to a file:

gws auth export --unmasked > creds.json
Enter fullscreen mode Exit fullscreen mode

Then point the CLI to that file:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json
Enter fullscreen mode Exit fullscreen mode

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)"
Enter fullscreen mode Exit fullscreen mode

Disable telemetry

To disable anonymous usage collection:

export GOOGLE_WORKSPACE_CLI_NO_TELEMETRY=1
Enter fullscreen mode Exit fullscreen mode

Discover available commands

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

Start with:

gws --help
Enter fullscreen mode Exit fullscreen mode

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"}'
Enter fullscreen mode Exit fullscreen mode

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

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

Upload a file

Use the +upload helper to upload a local file:

gws drive +upload ./budget.xlsx --name "2026 Budget"
Enter fullscreen mode Exit fullscreen mode

Work with Gmail

Send an email 

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

Reply to a message 

gws gmail +reply \
  --message-id <ID> \
  --body "Thanks!"
Enter fullscreen mode Exit fullscreen mode

Replace <ID> with the Gmail message ID.

Triage the inbox 

gws gmail +triage
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Show today’s agenda 

gws calendar +agenda --today
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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 🚀"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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}'
Enter fullscreen mode Exit fullscreen mode

The CLI also supports output options such as:

gws drive files list --params '{"pageSize":10}' --json
Enter fullscreen mode Exit fullscreen mode 
gws drive files list --params '{"pageSize":10}' --yaml
Enter fullscreen mode Exit fullscreen mode

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

View the current configuration with:

gws config
Enter fullscreen mode Exit fullscreen mode

Connect Google Workspace CLI to an AI coding agent

After authentication, install the bundled agent skills:

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

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.
Enter fullscreen mode Exit fullscreen mode 
Send a follow-up email via Google Workspace CLI.
Enter fullscreen mode Exit fullscreen mode 
Show today's Calendar agenda with gws, then summarize the meetings.
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)