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:

Bash
Copy
1npm install -g @googleworkspace/cli

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

Video: Installing Google Workspace CLI

Step 2: Setup Authentication

Run:

Bash
Copy
1gws 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:

Bash
Copy
1gws auth login --account [email protected]

Video: Authentication Setup

Step 4: Verify Setup

List files from Google Drive:

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

Send a test email from the terminal:

Bash
Copy
1gws gmail +send --to [email protected] --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:

Bash
Copy
1gws auth list

If no credentials appear, export them manually:

Bash
Copy
1gws auth export --unmasked > ~/gws-credentials.json
2export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=~/gws-credentials.json

Then run the verification command again:

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

Example Commands

View all available commands:

Bash
Copy
1gws --help

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

Send an email:

Bash
Copy
1gws gmail +send --to [email protected] --subject "From terminal" --body "Hello from the terminal!"

Get Gmail profile:

Bash
Copy
1gws 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