Google Workspace CLI (gws) Setup

The Google Workspace CLI (gws) is the primary internal tooling layer for Google Sheets, Drive, Docs, Gmail, and Calendar when working from the shell or scripts. It is not used by platform runtime code or Dagster jobs—those use direct APIs/service accounts.

When to use gws vs MCP vs runtime

Use case	Use
Product/runtime (Next.js calendar routes, Supabase directory sync, Dagster pipelines)	Direct Google APIs or SDKs; env-based credentials. Do not call `gws` from app or job code. Platform and Dagster use only Calendar (and Supabase uses Google Admin Directory); Gmail, Drive, and Docs are not used in runtime code.
Internal tooling, scripts, WBR/OKR updates	`gws` (this guide).
Cursor/agent workflows (GTM sheet context, Docs/Sheets from chat)	Prefer `gws` (this guide); use Google Workspace MCP when the CLI is not available or when MCP is better suited.

Prerequisites

Node.js 18+ (for npm install -g @googleworkspace/cli). Prefer the same Node version you use daily (e.g. nvm use 20) so gws is on your PATH.
A Google Cloud project with OAuth consent screen and a Desktop app OAuth client (e.g. Brainforge Prod).
Google account with access to the Sheets/Drive you need (e.g. uttam@brainforge.ai for the GTM review sheet).

Installation

npm install -g @googleworkspace/cli

Verify:

gws --version

If gws is not found, ensure the Node version active in your shell is the one you used for the global install (e.g. nvm use 20).

Authentication

1. OAuth client (one-time)

You need a Desktop app OAuth client in a GCP project (e.g. Brainforge Prod):

In Google Cloud Console, select the project.
APIs & Services → Credentials → Create credentials → OAuth client ID. (If you don’t see Credentials, use the left nav: APIs & Services → Credentials; the “Google Auth Platform / Clients” UI is a different surface.)
Application type: Desktop app. Name e.g. gws CLI. Create.
Download the JSON or copy Client ID and Client secret.

2. Configure gws

Option A — config file (recommended)

Save the downloaded JSON as:

~/.config/gws/client_secret.json

If the downloaded file has a long name, copy it:

mkdir -p ~/.config/gws
cp "/path/to/Downloads/client_secret_*.json" ~/.config/gws/client_secret.json

Option B — environment variables

export GOOGLE_WORKSPACE_CLI_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_WORKSPACE_CLI_CLIENT_SECRET="your-client-secret"

3. Log in

gws auth login -s sheets,drive

Use -s sheets,drive to limit scopes (helps with unverified app limits). If you need Gmail or Calendar (e.g. for meeting prep, weekly kick-off emails, or calendar reminders), include them:

gws auth login -s gmail,calendar,sheets,drive

Open the URL in your browser, sign in with your Google account, and complete consent. After that, credentials are stored locally and reused.

4. Test

gws auth status

Then read the GTM review sheet (see below). To log out or re-auth later: gws auth logout then gws auth login -s sheets,drive.

GTM Review Sheet (pilot workflow)

Spreadsheet ID: 1ovnNvvRxqk3V5yl7uGD1rwPKy9AXgEzrg8srbwAtqLE
URL: Brainforge: Weekly / Monthly / Quarterly GTM Review

Get spreadsheet metadata (tabs, structure)

gws sheets spreadsheets get --params '{"spreadsheetId":"1ovnNvvRxqk3V5yl7uGD1rwPKy9AXgEzrg8srbwAtqLE"}'

Read a range (e.g. OKRs Q1 2026)

Use the tab name as in the sheet. Example:

gws sheets spreadsheets values get --params '{"spreadsheetId":"1ovnNvvRxqk3V5yl7uGD1rwPKy9AXgEzrg8srbwAtqLE","range":"OKRs Q1 2026!A1:D30"}'

Update a range (controlled OKR update)

Use USER_ENTERED so formulas and formatting behave correctly:

gws sheets spreadsheets values update \
  --params '{"spreadsheetId":"1ovnNvvRxqk3V5yl7uGD1rwPKy9AXgEzrg8srbwAtqLE","range":"OKRs Q1 2026!A5:B5","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["Objective","Key result or update"]]}'

Replace the range and values with the cell(s) you intend to change. Always confirm in the sheet after an update.

Gmail, Calendar, Drive, Docs

gws supports Gmail, Calendar, Drive, and Docs in addition to Sheets. Use these for internal workflows (meeting prep, weekly kick-offs, partner/event follow-up emails, calendar reminders, or creating/sharing docs). Platform and Dagster do not call Gmail, Drive, or Docs APIs—only Calendar (and Supabase uses Admin Directory).

Scopes

Log in with the services you need: gws auth login -s gmail,calendar,sheets,drive. Add docs if you use Google Docs from the CLI. Unverified OAuth apps are limited to ~25 scopes; keep the list minimal.

Gmail (examples)

List recent messages:

gws gmail users messages list --params '{"userId":"me","maxResults":10}'

Get a message (use an id from the list):

gws gmail users messages get --params '{"userId":"me","id":"MESSAGE_ID"}'

Send and other actions use gws gmail users messages send (and related methods) with --json; see gws gmail --help and gws schema gmail.users.messages.list for request shapes.

Calendar (examples)

List events in a time window:

gws calendar events list --params '{"calendarId":"primary","timeMin":"2026-03-01T00:00:00Z","timeMax":"2026-03-31T23:59:59Z","singleEvents":true}'

Create/update/delete events use gws calendar events insert, update, delete with appropriate params and --json body. Use gws calendar --help and gws schema calendar.events.list to inspect options.

How this fits Brainforge workflows

Meeting prep / standup deck: Use Calendar to read “next meeting with [client]” or “this week’s syncs” and feed into briefs (see the meeting-prep and standup-deck Cursor skills and standards/04-prompts/meetings/).
Weekly kick-off, partner/event follow-up: Drafts are often sent by email or Slack; gws Gmail can send or list threads for follow-up (see playbook email templates and GTM agent PRDs in vault).
Client email context + follow-up drafting: Use gws Gmail and Calendar in the client comms SOP (standards/04-prompts/email-client-comms-sop.md) and follow communication standards (standards/02-writing/Communications/email-communication-standards.md).
WBR/OKR: Sheets (GTM review sheet) — see above.
Partnerships digest / reminders: Calendar events or reminders (e.g. Thursday cadence) can be created via gws calendar events insert.

The hosted Work product also uses Gmail, Calendar, Drive, Docs, and Sheets, but that code now lives outside this monorepo in brainforge-work. Cursor can use Gmail and Calendar via the Google Workspace MCP—see Setup: Google Workspace MCP for Cursor for the full tool list (search mail, get/send email, list/create/update/delete calendar events, free-busy). Use the MCP from Cursor when you need email or calendar; use gws from the shell or scripts when not in Cursor.

Credential storage

Local: ~/.config/gws/client_secret.json (OAuth client) and ~/.config/gws/credentials.enc or credentials.json (tokens). Do not commit these.
1Password: Store client IDs/secrets in Brainforge AI Team if you need to share setup with the team; document the item name in this guide.
CI/headless: Use gws auth export on a machine with a browser, then set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to the exported file on the headless host.

Follow-up

Work app: Audit and remove any embedded OAuth client ID/secret in the current brainforge-work repo. Move them to env vars or 1Password and document the runtime contract there.

Reference

Upstream: googleworkspace/cli (not an officially supported Google product).
MCP (Cursor): setup-google-workspace-mcp.md.
Calendar (product): google-calendar-clockify-setup.md.

Brainforge Knowledge

Explorer

google-workspace-cli-setup