Control All of Google Workspace from One CLI Tool

// Before you start

What you need

A Google account (personal or Workspace)
A Google Cloud project — free to create at console.cloud.google.com
Node.js 18+ installed (check with: node --version) OR Homebrew on Mac
Basic comfort opening a terminal and running commands
You must add yourself as a Test User in your Google Cloud OAuth consent screen

Step 1 of 7

Install gws on your machine

3 min

You have three easy options. If you are on a Mac with Homebrew, use that. If you have Node.js installed, use npm. Otherwise download the binary directly from the GitHub Releases page at https://github.com/googleworkspace/cli/releases — pick the file matching your OS and chip, unzip it, and move the gws file somewhere on your PATH (like /usr/local/bin on Mac/Linux). The npm route is the most universal for people who already have Node.

Terminal · mac

$ npm install -g @googleworkspace/cli

What you should see

added 1 package ... gws@x.x.x Run `gws --help` to get started

This might happen

npm: permission denied error on Mac/Linux

Run: sudo npm install -g @googleworkspace/cli — then enter your Mac password when prompted.

Step 2 of 7

Confirm gws is working

1 min

Before touching Google credentials, make sure the tool installed correctly. This command prints the version number. If you see a version, you are ready to move on.

Terminal · mac

$ gws --version

What you should see

gws x.x.x

This might happen

Command not found after npm install

Close your terminal, open a new one, and try again. npm sometimes needs a fresh shell to update the PATH.

Step 3 of 7

Create a Google Cloud project and OAuth credentials

10 min

gws needs an OAuth 'client' from your own Google Cloud project to talk to Google's APIs on your behalf. Go to https://console.cloud.google.com and create a new project (any name). Then visit the OAuth consent screen page, set App type to External, and add your own Google email under Test Users. Next go to Credentials, click Create Credentials → OAuth client ID, choose Desktop app, and download the JSON file. Save that file to the exact path shown in the command below. This is the most involved step — take it slowly.

Terminal · mac

$ mkdir -p ~/.config/gws && mv ~/Downloads/client_secret*.json ~/.config/gws/client_secret.json

What you should see

No output means success. Confirm with: ls ~/.config/gws/

This might happen

The downloaded file has a long random name and may not match the mv pattern

Rename it manually first: in your Downloads folder, rename the file to client_secret.json, then run: mv ~/Downloads/client_secret.json ~/.config/gws/client_secret.json

Step 4 of 7

Log in and authorize gws

3 min

This command opens a browser window where you approve which Google services gws can access. Because your app is in 'testing mode' (unverified), Google will show a warning screen — click Continue to proceed. To avoid hitting a scope limit with unverified apps, log in with only the services you actually need. The example below requests Drive and Gmail only. Add or remove services separated by commas.

Terminal · mac

$ gws auth login -s drive,gmail

What you should see

A browser tab opens. After you approve, the terminal prints: Authentication successful.

This might happen

Browser shows 'Access blocked' or login fails immediately

You forgot to add yourself as a Test User. Go back to your Google Cloud project → OAuth consent screen → Test users → Add users, enter your email, save, then retry.

Step 5 of 7

Run your first real command — list Drive files

1 min

Now test that everything works end-to-end. This command asks Google Drive to return the 5 most recently modified files in your Drive and prints them as JSON. You should see file names, IDs, and types in the output.

Terminal · mac

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

What you should see

{ "files": [ { "id": "...", "name": "...", "mimeType": "..." }, ... ] }

This might happen

Error: insufficient authentication scopes

You logged in without the drive scope. Re-run: gws auth login -s drive — then try the list command again.

Step 6 of 7

Try a few more useful commands

2 min

Here are three ready-to-use commands to explore. The first lists your 10 most recent Gmail threads. The second creates a new Google Sheet. The third uses --dry-run to preview a Chat message without actually sending it — safe to experiment with. Copy and run whichever ones match the services you authorized.

Terminal · mac

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

$ gws sheets spreadsheets create --json '{"properties": {"title": "My New Sheet"}}'

$ gws chat spaces messages create --params '{"parent": "spaces/REPLACE_WITH_SPACE_ID"}' --json '{"text": "Hello from gws!"}' --dry-run

What you should see

Gmail: JSON list of thread objects. Sheets: JSON with the new spreadsheet ID and URL. Chat dry-run: prints the request that would be sent, no message delivered.

This might happen

Gmail or Sheets command returns a 403 forbidden error

You need to re-login with those scopes added: gws auth login -s drive,gmail,sheets — then retry.

Step 7 of 7

Explore any API method with built-in help

1 min

gws builds its commands dynamically from Google's own API catalog, so it covers hundreds of methods. Use --help on any command to see what parameters it accepts. Use gws schema to inspect the exact JSON shape a method expects or returns. This replaces reading Google's REST documentation.

Terminal · mac

$ gws drive files --help

$ gws schema drive.files.list

What you should see

A list of available sub-commands and flags for Drive files, followed by the full JSON schema for the list method.

// Status

cooked. baked. worked.

A working gws installation that can list, create, and manage files, emails, sheets, and other Google Workspace resources from your terminal using simple copy-paste commands.

// the honest bit

The honest part

This project is under active development and explicitly warns of breaking changes before v1.0. Your OAuth app stays in 'testing mode' unless you submit it for Google verification — unverified apps are limited to about 25 scopes and only the test users you manually add can log in. Service Account and CI setups require additional steps not covered here. The gws auth setup shortcut (which automates Cloud project creation) requires the separate gcloud CLI tool — this guide skips it and uses manual setup instead.