Google Workspace CLI Integration

Overview

The Google Workspace CLI provides a command-line interface for working with Gmail, Docs, Sheets, and other Google Workspace services. Use it to script workflows, automate tasks, and build tools that interact with your emails, documents, and spreadsheets from your terminal.

Prerequisites

• Node.js and npm
• A Google account with access to Google Workspace services
• A Google OAuth application (Google Cloud Console)
• A terminal (Cursor, VS Code terminal, or standard terminal)

Setup Instructions

Step 1: Install the CLI

Open your terminal and run:

npm install -g @googleworkspace/cli

Once installed, the gws command is available in your terminal.

Video: Installing Google Workspace CLI

Step 2: Setup Authentication

Run:

gws auth setup

If the CLI reports a missing dependency, install it when prompted and run the command again.

Credentials are typically stored at:

~/.config/gws/client_secret.json

You may need to create or configure a Google OAuth client depending on your environment.

Step 3: Login

Authenticate with your Google account:

gws auth login --account your_email_here@gmail.com

Video: Authentication Setup

Step 4: Verify Setup

List files from Google Drive:

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

Send a test email from the terminal:

gws gmail +send --to your_email_here@gmail.com --subject 'from terminal' --body 'hello! from the terminal!'

Video: Testing the CLI

Step 5: Troubleshooting Authentication

If commands do not return results, check authentication status:

gws auth list

If no credentials appear, export them manually:

gws auth export --unmasked > ~/gws-credentials.json
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=~/gws-credentials.json

Then run the verification command again:

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

Example Commands

View all available commands:

gws --help

The CLI includes 100+ prebuilt skills for different Google Workspace APIs. Full list: skills.md

Send an email:

gws gmail +send --to example@email.com --subject "From terminal" --body "Hello from the terminal!"

Get Gmail profile:

gws gmail users getProfile --params '{"userId": "me"}'

What You Can Build

• Automated email workflows
• AI agents that use Workspace tools
• Scripts that read or update Google Sheets
• Internal tools powered by Workspace APIs

Demo Video

End to end install: Demo