Guide

Google Workspace CLI: Limits and Alternative

Google Workspace CLI (gws) gives you Gmail, Drive, Calendar, Sheets, and Docs from one terminal command. This guide covers what gws does well, where its OAuth setup and pre-1.0 status bite, and when a multi-provider CLI is the better fit for email and calendar work.

Written by Qasim Muhammad Staff SRE

Verified — CLI 3.1.17 · Gmail, Outlook · last tested June 9, 2026

What is the Google Workspace CLI (gws)?

Google Workspace CLI (gws) is an open-source command-line tool from Google's Workspace developer team, released June 2, 2026. Written in Rust under an Apache 2.0 license, it builds its command surface at runtime from Google's Discovery Service and covers Gmail, Drive, Calendar, Sheets, Docs, Chat, Admin, and the rest of the Workspace API catalog.

The gws repository passed 26,500 GitHub stars in its first week and ships more than 100 bundled agent skills for AI coding tools. Two README lines matter before you build on it: "This is not an officially supported Google product" and "Expect breaking changes as we march toward v1.0."

Don't confuse gws with GAM, the long-running community tool for Workspace admins. GAM manages users, groups, and domain settings through admin credentials. gws is aimed at end users and AI agents acting on one account's mail, files, and events, so searches for "google workspace cli vs gam" are really comparing 2 different jobs.

Why does gws auth login fail so often?

The gws auth login flow fails most often because of Google's own OAuth verification rules. An unverified OAuth app in testing mode is limited to roughly 25 scopes per consent, while the gws recommended scope preset requests 85+ scopes. The README itself warns that the recommended preset will fail for unverified apps.

Before the first command runs, you create a Google Cloud project, configure an external OAuth consent screen, add yourself as a test user, create a Desktop OAuth client, and save the downloaded JSON to ~/.config/gws/client_secret.json. InfoQ's launch coverage relayed a Hacker News user who spent about 45 minutes in that flow, picked the recommended scopes, and still ended at a browser authentication error.

The issue tracker filled with auth reports in the first weeks. Issue #25 documents first-run logins dying on Error 403: restricted_client. Issue #119 reported v0.3.4 rejecting personal @gmail.com accounts with 400 invalid_scope because the preset included admin-only scopes (since fixed). Issue #316 notes the interactive picker lists only 9 scopes, so services like People and Chat return 403 insufficient-scope errors, and issue #187 describes logins looping back to an unknown-account state.

Is Google Workspace CLI production-ready?

Not yet, by its own description. The gws README states "This is not an officially supported Google product" and tells users to expect breaking changes before v1.0. For a script that runs once on your laptop that's fine. For a cron job or an agent pipeline, an unversioned command surface is a real operational risk.

The runtime Discovery Service design cuts both ways. New Google endpoints appear in gws automatically without a release, which is genuinely useful. But the same mechanism means commands can change or disappear without a changelog entry, and InfoQ's June 2026 launch coverage noted community concern that an agent could break mid-workflow if Google retires an endpoint the tool discovered yesterday.

The boundary is also hard: gws speaks to Google's 8+ Workspace services and nothing else. A teammate on Microsoft 365, a customer on Exchange, or a monitoring inbox on IMAP needs a second tool with a second grammar, which is exactly the situation a unified CLI was supposed to end.

When is gws the right tool?

Use Google Workspace CLI when everything you automate lives inside Google's services and you need more than mail. It is the only CLI that drives Sheets, Docs, Drive, and Chat alongside Gmail and Calendar from one binary, and it ships over 100 skills that plug directly into Gemini CLI and other coding agents.

It's also free and Apache 2.0 licensed, so there's no procurement step. If your team is all-in on Workspace, owns a Google Cloud project already, and can tolerate pre-1.0 churn, the setup cost amortizes quickly. Spreadsheet automation alone justifies it: no other terminal tool reads and writes Sheets ranges without custom API code.

The wrong reason to pick gws is "we need email and calendar from the terminal." That subset of the job is where its Google-only boundary, OAuth consent friction, and stability warnings cost the most, and where an alternative exists with none of those constraints.

What is the multi-provider alternative for email and calendar?

Nylas CLI is the email and calendar alternative: one command grammar across Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP. Authentication is an API key, not an OAuth client you build yourself, so there's no Google Cloud project, no consent screen, no test-user list, and no 25-scope ceiling to plan around.

Setup takes about 2 minutes. Install with Homebrew (other methods are in the getting started guide), run the nylas init wizard to connect your account, and list a connected inbox in the same session. The final command below ran against both a Gmail and an Outlook grant on CLI version 3.1.17, returning identical JSON shapes from each provider.

brew install nylas/nylas-cli/nylas
nylas init
nylas email list --limit 25 --json

The command reference pages for this flow are nylas init and nylas email list. For CI, a container, or an agent sandbox where no browser exists, skip the wizard and store a key directly with nylas auth config --api-key.

How do gws and Nylas CLI compare?

The comparison comes down to breadth versus portability. gws covers 8+ Google services on one provider; Nylas CLI covers email, calendar, and contacts on 6 providers. The table summarizes the differences that decide real projects: auth effort, stability guarantees, and what happens when a non-Google mailbox shows up.

DimensionGoogle Workspace CLI (gws)Nylas CLI
ServicesGmail, Drive, Calendar, Sheets, Docs, Chat, Admin, moreEmail, calendar, contacts
ProvidersGoogle onlyGmail, Outlook, Exchange, Yahoo, iCloud, IMAP
Auth setupOwn Google Cloud project, OAuth consent screen, scope selectionAPI key, one config command
Unverified-app scope cap~25 scopes (preset needs 85+)Not applicable
StabilityPre-1.0, breaking changes expected, commands discovered at runtimeVersioned releases (3.1.17 tested here)
Support"Not an officially supported Google product"Commercially supported product
Agent tooling100+ bundled skills, Gemini CLI extensionMCP server install, app-owned Agent Accounts
License / costApache 2.0, freeFree CLI; Nylas API plans for connected accounts

If your workload is Sheets and Drive automation, the right column never enters the picture. If it's inbox triage, calendar checks, or agent mail across customers on different providers, the left column's Google-only boundary is disqualifying on its own.

How do I run one workflow across Gmail and Outlook?

A cross-provider workflow uses the same Nylas CLI syntax no matter which backend holds the mailbox. The 3 commands below check the week's calendar, scan recent mail, and send a message. Each was verified on June 9, 2026 against a Gmail grant and an Outlook grant with zero syntax changes between them.

nylas calendar events list --days 7 --json
nylas email list --limit 25 --json
nylas email send --to ops@company.com --subject "Daily check" --body "All clear" --yes

The --yes flag skips the confirmation prompt so sends run unattended in cron or CI. Switching the active account is one nylas auth switch command, and nylas calendar events list documents the date-range flags used above.

Next steps