Google Workspace CLI: Automate Gmail, Drive & Calendar From Your Terminal

Every day, millions of people play the same inefficient game: open Gmail, click around, open Drive in another tab, search for a file, jump to Calendar, paste something into a Doc. It's fine — but it's also thousands of tiny clicks that add up to hours you'll never get back.

Something changed in early March 2026. Google quietly shipped a tool that lets you talk to all of that — Gmail, Drive, Calendar, Sheets, Docs, Chat — from a single line in your terminal. It's called gws, and it hit #1 on Hacker News with over 500 points and 22,000 GitHub stars in its first week.

This isn't just for developers. If you've ever wished Google Workspace would just do something for you — and you're willing to spend 20 minutes setting it up — this is your starting point.

⚠️ Heads up: gws is pre-v1 and not officially supported by Google. It's open source (Apache 2.0). Great for personal automation and experiments — not recommended for production without thorough testing first.

What Is the Google Workspace CLI?

Think of gws as a universal remote for your entire Google Workspace. Instead of navigating between five different apps in your browser, you type a command and get an instant, structured result. No loading screens. No clicking. No switching tabs.

What makes it genuinely clever: rather than shipping a fixed list of commands, it reads Google's own Discovery Service at runtime and builds its command surface on the fly. That means when Google adds a new API endpoint, gws picks it up automatically — no package update required. Every response comes back as structured JSON, which plays beautifully with AI agents, shell scripts, and anything else that reads clean data.

How Power Users Are Actually Using It

The Monday morning inbox briefing

The most cited use case since launch. Instead of opening Gmail and drowning in unread emails, users are wiring up an AI agent — Claude Code, Gemini CLI, or anything that can run terminal commands — to process their inbox automatically:

Prompt to your AI agent: Read my last 10 emails. For each one, decide if it's urgent, needs action, or is just informational. Then create a Google Slides deck called "Executive Briefing", a Google Doc called "Weekly Briefing Notes", and log all 10 to a Google Sheet with columns for sender, priority, deadline, and action item.

Before gws, that was a Zapier workflow, three separate APIs, and a weekend of debugging. Now it's one prompt to an agent that already has access to everything.

Contract & document workflows

An agent reads a new contract email, extracts key terms into a shared Google Doc, files attachments in Drive, pings the legal team in Chat, and flags the review deadline in Calendar — all triggered by a single incoming email. This kind of multi-step, cross-app automation was previously only possible with custom API code or expensive no-code platforms.

Replacing Zapier for Workspace-native flows

For workflows that live entirely within Google Workspace, gws can replace paid automation tools. No per-operation pricing, no workflow builder to learn, no platform lock-in. Community members report replacing $50–$100/month Zapier plans for their Workspace automations.

⚡ Key limitation: gws is Google-to-Google. If your workflow needs Salesforce, HubSpot, or Slack, you'll still need Zapier or n8n for those connections. But for workflows that stay inside Workspace, this covers the automation layer you've been paying monthly for.

Setup in 4 Steps

Step 1 — Install Node.js, then install gws

Check if you have Node by typing node --version in your terminal. If not, download it from nodejs.org. Then run:

npm install -g @googleworkspace/cli

# Verify it installed correctly
gws --version

Step 2 — Create a Google Cloud project

Go to console.cloud.google.com, create a new project (any name), then navigate to APIs & Services → Credentials → Create OAuth 2.0 Client ID and select Desktop app. Download the JSON file — that's your key.

If you already have gcloud CLI installed, skip all of this and just run gws auth setup — it handles the entire Cloud project setup automatically.

Step 3 — Authenticate

gws auth login
# Browser opens → approve access → done
# Credentials are encrypted and stored in your OS keyring

⚠️ Gmail accounts in testing mode: Google limits unverified apps to ~25 OAuth scopes. When you see the scope picker, choose individual services (just Gmail, or just Drive) rather than "select all" to avoid hitting this limit.

Step 4 — Enable the API & run your first command

Enable the specific API (Drive, Gmail, etc.) for your project in the Cloud Console dashboard, then try your first command:

# List your Google Drive files
gws drive files list

# Limit to top 10 results
gws drive files list --params '{"pageSize": 10}'

# Check upcoming calendar events
gws calendar events list --params '{"calendarId":"primary","maxResults":5}'

# Explore all available commands for a service
gws gmail --help

Vibe Code Your First Automation

You don't need to write scripts from scratch. Describe what you want in plain language, paste it into Claude, ChatGPT, or Gemini, and get working code back in minutes. Here are three ready-to-use prompts.

Template 1 — Morning email digest

Write a bash script that uses the Google Workspace CLI (gws) to fetch
my last 20 unread Gmail messages as JSON, summarize each one using
Claude, and save the output as morning-brief.md in my home directory.
Include sender, subject, and a one-sentence summary per email.

Template 2 — Auto-file attachments to Drive

Write a Python script that uses gws (via subprocess) to search Gmail
for emails with PDF attachments from the last 7 days, downloads each
attachment, and uploads it to a Google Drive folder called
"Inbox Attachments" using gws drive files create with the --upload flag.

Template 3 — Weekly Sheets report (cron-ready)

Write a bash script I can run via cron every Friday at 5pm. It should
use gws to append a row to a Google Sheet (ID: YOUR_ID_HERE) with
today's date, the number of emails I received this week (from gws gmail),
and the number of calendar events I had (from gws calendar).

💡 Key to great results: Always tell your AI (1) which gws service you're targeting, (2) that outputs are JSON, and (3) exactly what the final result should be — a file, an email, a Sheet row. The more specific about the end state, the cleaner the code you'll get back.

Which Type of Power User Are You?

Honest Caveats Before You Dive In

It's pre-v1. Commands, flags, and output formats may change between releases. If you're building something important, pin to a specific version: npm install -g @googleworkspace/cli@x.x.x.

Setup takes ~20–30 minutes. The Google Cloud project step is the main friction point. Use gws auth setup if you have gcloud — it automates most of it.

Scope limits affect personal Gmail accounts. In testing mode, Google caps unverified apps at ~25 OAuth scopes. Select individual services in the scope picker, not "all".

Not a multi-platform tool. gws covers everything inside Google's ecosystem. For workflows that touch external tools like Slack or Salesforce, you'll still need a connector layer.

Get Started Today

One command to install. One weekend to automate the thing that's been annoying you for months.

• 🐙 GitHub Repo
• 📦 npm Package
• 📖 Agent Skills Docs

npm install -g @googleworkspace/cli

Prefer No-Code? Try 8apps Add-ons

If terminal commands aren't your thing, you can still automate Google Workspace using our ready-made add-ons. They run natively inside Gmail, Sheets, and Drive without complex setup:

• Contact Extractor: Instantly build your sales list by pulling names, emails, and phone numbers from Gmail into Google Sheets.
• Currency Converter: Effortlessly convert live currency values directly within your Google Sheets.
• Drive Guard: Audit and manage file permissions securely across your Google Drive.
• GPT Mate: Draft emails and content automatically by bringing ChatGPT and Gemini right into Google Docs and Sheets.
• Hash Data: Protect sensitive Information and PII by quickly hashing data in Google Sheets.
• Mail My Sheets: Automate your reporting by seamlessly emailing snapshots of your Sheets on a schedule.
• Mail to Drive: Keep records safe by automatically saving important emails and attachments as PDFs to Drive.

Have a custom workflow in mind?
We can build a bespoke Google Workspace add-on tailored precisely to your business processes. Write to us at support@8apps.co to get started!