Google Workspace CLI (gws) — Complete Setup & Integration Guide

Author: Ryan Cassidy Last Updated: March 2026 Platform: macOS (Apple Silicon / Intel)

Table of Contents

1. What Is gws and Why Use It?
2. Prerequisites
3. Part 1 — Installing the CLI
4. Part 2 — Installing Google Cloud SDK (gcloud)
5. Part 3 — Creating a GCP Project
6. Part 4 — OAuth Consent Screen & Credentials
7. Part 5 — Authenticating gws
8. Part 6 — Verifying the Installation
9. Part 7 — Installing Agent Skills for OpenAI Codex
10. Part 8 — Installing Agent Skills for Claude Code / OpenClaw
11. Scope Reference
12. Troubleshooting
13. Basic Usage Examples
14. Example: Creating a Custom Codex Skill
15. Example: Using Codex to Create and Email a Document
16. Example: Using Codex to Schedule a Recurring Calendar Event
17. Example: Asking Codex to Research and Log Findings to a Sheet
18. Updating & Maintenance
19. Key File Locations

1. What Is gws and Why Use It?

gws (Google Workspace CLI) is an open-source, community-maintained command-line tool that provides a unified interface to every Google Workspace API — Drive, Gmail, Calendar, Sheets, Docs, Slides, Tasks, Chat, Admin, and more.

Unlike traditional REST API wrappers, gws dynamically reads Google's Discovery Service at runtime and builds its entire command surface on the fly. When Google adds a new API endpoint, gws picks it up automatically without needing an update.

Why it matters for developers and AI agents:

• Every response is structured JSON, making it trivial to parse and chain with other tools.
• It ships with 100+ agent skills (SKILL.md files) compatible with OpenAI Codex, Claude Code, OpenClaw, and Gemini CLI.
• It handles OAuth2 authentication, auto-pagination, multipart uploads, and schema introspection out of the box.
• It eliminates the need to write custom Google API boilerplate for each service.

Important: This is not an officially supported Google product. It is an open-source project under the Apache-2.0 license.

Repository: github.com/googleworkspace/cli

2. Prerequisites

Before starting, make sure you have the following:

Optional but recommended:

Installing Node.js (if missing)

Via Homebrew:

brew install node

Via nvm (recommended for managing multiple versions):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.zshrc
nvm install 20
nvm use 20

Installing Homebrew (if missing)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

After installation, follow the instructions Homebrew prints to add it to your PATH. On Apple Silicon Macs, this is typically:

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
source ~/.zshrc

3. Part 1 — Installing the CLI

Run this from your home directory (or anywhere — it installs globally):

npm install -g @googleworkspace/cli

Expected output:

added 43 packages in 2s
12 packages are looking for funding
  run `npm fund` for details

Verify it installed:

gws --version

What can go wrong here

Fixing npm permission errors:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @googleworkspace/cli

4. Part 2 — Installing Google Cloud SDK (gcloud)

The gws auth setup command uses gcloud to automate project creation, OAuth consent screen configuration, and credential generation. Without it, you'll need to do all of that manually in the Google Cloud Console.

Why this step is needed

When you run gws auth setup without gcloud installed, you'll see:

{
  "error": {
    "code": 400,
    "message": "gcloud CLI not found. Install it from https://cloud.google.com/sdk/docs/install",
    "reason": "validationError"
  }
}

This is not a failure of gws — it's telling you it needs gcloud to proceed with the automated setup.

Installation

brew install --cask google-cloud-sdk

This installs gcloud along with its dependencies (Python 3.13, OpenSSL, SQLite, etc.). The process takes a few minutes.

After installation, note the PATH caveat Homebrew prints:

To use additional binary components installed via gcloud, add the
"/opt/homebrew/share/google-cloud-sdk/bin" directory to your PATH

If gcloud isn't found after install, add this to your ~/.zshrc:

source /opt/homebrew/share/google-cloud-sdk/path.zsh.inc
source /opt/homebrew/share/google-cloud-sdk/completion.zsh.inc

Then reload: source ~/.zshrc

Python version warning

You may see this warning during or after installation:

WARNING: Python 3.9.x is no longer officially supported by the Google Cloud CLI
and may not function correctly. Please use Python version 3.10 and up.

This happens when gcloud picks up an older system Python. The fix:

export CLOUDSDK_PYTHON=/opt/homebrew/bin/python3.13

Add that to your ~/.zshrc to make it permanent. In practice, this warning doesn't block anything — gcloud still works.

5. Part 3 — Creating a GCP Project

Initialize gcloud

gcloud init

This opens your browser for Google account authentication. Sign in with the Google account you want to use for Workspace access.

After signing in, you'll see a project picker:

Pick cloud project to use:
 [1] example-project-one
 [2] example-project-two
 [3] example-project-three
 [4] Enter a project ID
 [5] Create a new project

Should you create a new project or reuse one?

Create a new, dedicated project. Here's why:

• Separation of concerns: Mixing OAuth credentials across production apps creates security and management headaches. If you revoke gws access, you don't want it touching credentials for other apps.
• Scope isolation: gws requests broad OAuth scopes (Drive, Gmail, Calendar, Sheets, etc.). Keeping that separate from production apps avoids accidental scope leakage.
• Quota isolation: Each GCP project has independent API quotas. Heavy agent usage of gws (paginating Drive, bulk-reading Gmail) won't eat into quotas your production apps depend on.

Creating the project

Select Create a new project, then enter a project ID:

Enter a Project ID. Note that a Project ID CANNOT be changed later.
Project IDs must be 6-30 characters (lowercase ASCII, digits, or
hyphens) in length and start with a lowercase letter.

A good naming convention: yourcompany-workspace-cli (e.g., mycompany-workspace-cli).

Expected output:

Waiting for [operations/create_project.global.xxxxxxxxxxxxx] to finish...done.
Your current project has been set to: [mycompany-workspace-cli].

You can skip the default zone/region prompt — it's only needed for Compute Engine and isn't relevant to Workspace APIs.

6. Part 4 — OAuth Consent Screen & Credentials

Attempt the automated setup first

gcloud config set project mycompany-workspace-cli   # ensure correct project
gws auth setup

If gws auth setup can fully automate this (creating the consent screen and OAuth client via gcloud), it will prompt:

Run `gws auth login` now? [Y/n]: y

Say yes and skip to Part 5.

If gws auth setup asks for manual OAuth credentials

In some cases, gws auth setup cannot fully automate the consent screen and will display:

Manual OAuth client setup required.

Step A — Consent screen (if not configured):
https://console.cloud.google.com/apis/credentials/consent?project=mycompany-workspace-cli

Step B — Create an OAuth client:
https://console.cloud.google.com/apis/credentials?project=mycompany-workspace-cli

Enter OAuth Client ID> _

Don't type anything yet. You need to go set things up in your browser first.

Step A — Configure the OAuth Consent Screen

1. Open the consent screen URL from your terminal in your browser
2. Click Get Started (or Configure Consent Screen depending on the UI version)
3. Fill in the required fields:
   • App name: gws-cli (or anything descriptive)
   • User support email: Your Google email address
   • Developer contact email: Your Google email address
4. For User Type / Audience, select External
5. Click Save and Continue through each screen (Scopes, Test Users, Summary)
6. Critical step — Add yourself as a Test User:
   • On the Test Users screen, click Add Users
   • Enter your Google email address (the same one you'll authenticate with)
   • Click Add, then Save and Continue

If you skip adding yourself as a test user, you will get an "Access blocked" error during login.

Step B — Create OAuth Credentials

1. Go to the Credentials URL from your terminal
2. Click + Create Credentials at the top
3. Select OAuth client ID
4. For Application type, select Desktop app
5. For Name, enter gws-cli
6. Click Create
7. A popup appears with your Client ID and Client Secret — keep this open

Step C — Enter credentials into the terminal

Go back to your terminal where gws auth setup is waiting:

1. Paste the Client ID and press Enter
2. It will ask for the Client Secret — paste that and press Enter

The setup will save the client configuration to ~/.config/gws/client_secret.json.

7. Part 5 — Authenticating gws

Choosing scopes

After setup completes, gws will launch a scope selection TUI (terminal UI). This is where you choose which Google APIs you want to authorize.

Critical warning: Unverified apps in testing mode are limited to approximately 25 OAuth scopes. The "Recommended" preset includes 85+ scopes and will fail for unverified apps (especially @gmail.com accounts).

Do NOT select the "Recommended" preset with all 100+ scopes. Instead, manually select only the scopes you need.

Use the arrow keys to navigate the list and Space to toggle a checkbox on or off. If you accidentally selected the Recommended preset, arrow up to it and press Space to deselect all, then individually pick the scopes you need.

Recommended starting scopes

That puts you well under the 25-scope limit. You can always add more later.

Completing the OAuth flow

After confirming your scopes, gws will print a URL:

Open this URL in your browser to authenticate:
  https://accounts.google.com/o/oauth2/auth?scope=...

1. Open that URL in your browser
2. Sign in with your Google account
3. If you see "Google hasn't verified this app" — this is expected for testing-mode apps:
   • Click Advanced
   • Click Go to gws-cli (unsafe)
   • This is safe — verification is only required for apps published to external users
4. If scope checkboxes appear, select all of them and continue
5. The browser will redirect to localhost and you'll see "Authentication successful"

Expected terminal output on success

{
  "account": "you@gmail.com",
  "credentials_file": "/Users/yourname/.config/gws/credentials.enc",
  "encryption": "AES-256-GCM (key in OS keyring...)",
  "message": "Authentication successful. Encrypted credentials saved.",
  "scopes": [
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/documents",
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/presentations",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/tasks",
    "https://www.googleapis.com/auth/cloud-platform",
    "openid",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  "status": "success"
}

Your credentials are now encrypted at rest (AES-256-GCM) with the encryption key stored in your macOS Keychain.

Adding more scopes later

You can re-run gws auth login at any time with additional scopes:

gws auth login -s drive,gmail.modify,sheets,calendar,slides,docs,tasks

This re-does the OAuth flow with the new scope set. Existing credentials are replaced.

8. Part 6 — Verifying the Installation

Run a quick test to confirm everything is working:

# Check auth status
gws auth status

# List your 3 most recent Drive files
gws drive files list --params '{"pageSize": 3}'

# Introspect a method's schema
gws schema drive.files.list

If the Drive files command returns JSON with your files, you're fully operational.

9. Part 7 — Installing Agent Skills for OpenAI Codex

gws ships 100+ agent skills as SKILL.md files that follow the open agent skills standard used by OpenAI Codex.

Understanding skill locations in Codex

Since gws is a general-purpose tool you'll want everywhere, install at the user level.

Step-by-step installation

Run all commands from your home directory (~):

# 1. Create a folder for utility repos (not Desktop — keep it organized)
mkdir -p ~/repos

# 2. Clone the gws repo
cd ~/repos
git clone https://github.com/googleworkspace/cli.git gws-cli

# 3. Verify the skills directory exists and has content
ls ~/repos/gws-cli/skills/
# Expected: gws-drive/ gws-gmail/ gws-sheets/ gws-calendar/ gws-shared/ etc.

# 4. Create the Codex user-level skills directory
mkdir -p ~/.codex/skills

# 5. Symlink each gws skill into Codex
for skill in ~/repos/gws-cli/skills/gws-*; do
  ln -s "$skill" ~/.codex/skills/$(basename "$skill")
done

# 6. Verify the symlinks
ls -la ~/.codex/skills/
# Expected: gws-drive -> /Users/yourname/repos/gws-cli/skills/gws-drive
#           gws-gmail -> /Users/yourname/repos/gws-cli/skills/gws-gmail
#           etc.

# 7. Verify a skill file exists and has content
cat ~/.codex/skills/gws-drive/SKILL.md

Why symlinks instead of copying

Symlinks mean the skills stay in sync with the upstream repo. When the gws team ships updates:

cd ~/repos/gws-cli
git pull

Codex immediately picks up the changes — no re-copying needed.

Using the skills in Codex

Explicit invocation — type $ in the Codex composer to open the skill picker:

$gws-drive list my 10 most recent files
$gws-gmail send a summary email to me
$gws-sheets append a row to the Q1 Budget spreadsheet

Implicit invocation — Codex can match skills automatically based on your prompt:

Find all PDFs in my Google Drive from last week
Create a new Google Doc titled "Architecture Notes"

Verify in Codex — run /skills to see all installed skills.

Alternative: Use the built-in skill installer

Inside a Codex session, type:

$skill-installer install skills from https://github.com/googleworkspace/cli

Or install specific skills only:

$skill-installer install https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
$skill-installer install https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

10. Part 8 — Installing Agent Skills for Claude Code / OpenClaw

Claude Code

Drop the relevant skills into your project's .claude/ directory:

# Inside a project
mkdir -p .claude/skills
ln -s ~/repos/gws-cli/skills/gws-drive .claude/skills/gws-drive
ln -s ~/repos/gws-cli/skills/gws-gmail .claude/skills/gws-gmail
ln -s ~/repos/gws-cli/skills/gws-sheets .claude/skills/gws-sheets

OpenClaw

Symlink all skills into the OpenClaw skills directory:

# Symlink all (stays in sync with repo)
ln -s ~/repos/gws-cli/skills/gws-* ~/.openclaw/skills/

# Or copy specific skills
cp -r ~/repos/gws-cli/skills/gws-drive ~/.openclaw/skills/
cp -r ~/repos/gws-cli/skills/gws-gmail ~/.openclaw/skills/

The gws-shared skill includes an install block so OpenClaw will auto-install the CLI via npm if gws isn't on PATH.

11. Scope Reference

These are the most commonly needed scopes and what they enable:

Rule of thumb: Start with only what you need. You can always add more later with gws auth login -s scope1,scope2,....

12. Troubleshooting

gcloud CLI not found when running gws auth setup

Cause: gcloud isn't installed or isn't in your PATH.

Fix:

brew install --cask google-cloud-sdk
source /opt/homebrew/share/google-cloud-sdk/path.zsh.inc

If you'd rather skip gcloud entirely, you can do the manual OAuth setup in the Google Cloud Console instead.

gcloud: command not found after Homebrew install

Cause: Shell doesn't know where Homebrew installed it.

Fix: Add these lines to ~/.zshrc:

source /opt/homebrew/share/google-cloud-sdk/path.zsh.inc
source /opt/homebrew/share/google-cloud-sdk/completion.zsh.inc

Then reload: source ~/.zshrc

Access blocked or 403 during OAuth login

Cause: Your OAuth app is in testing mode and your account is not listed as a test user.

Fix:

1. Open the OAuth consent screen in your GCP project
2. Go to Test users
3. Click Add users
4. Enter your Google email address
5. Save, then retry gws auth login

Google hasn't verified this app warning

Cause: Expected behavior for apps in testing mode.

Fix: Click Advanced → Go to (app name) (unsafe). This is safe for personal use. Verification is only required for apps published to external users.

Too many scopes / consent screen error

Cause: Unverified (testing mode) apps are limited to ~25 OAuth scopes. The "Recommended" preset exceeds this.

Fix: Select only the scopes you need:

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

redirect_uri_mismatch

Cause: The OAuth client was created as a "Web application" instead of "Desktop app."

Fix:

1. Go to the Credentials page in your GCP project
2. Delete the existing OAuth client
3. Create a new one with type Desktop app
4. Download the new JSON or re-enter the Client ID / Secret

accessNotConfigured — API not enabled

Cause: The specific Google API hasn't been enabled for your project.

Fix: The error includes an enable_url. Click it, enable the API in the console, wait 10 seconds, then retry. Or run gws auth setup which can enable APIs automatically.

gws: command not found after npm install

Cause: npm global bin directory not in PATH.

Fix:

# Find where npm installed it
npm bin -g

# Add that directory to your PATH in ~/.zshrc
export PATH=$(npm bin -g):$PATH
source ~/.zshrc

EACCES: permission denied during npm install

Cause: System-level npm directory requires root access.

Fix (recommended):

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @googleworkspace/cli

Skills not showing up in Codex

Cause: Symlinks are broken, skills directory doesn't exist, or Codex needs a restart.

Fix:

# Check symlinks aren't broken
ls -la ~/.codex/skills/

# If you see red entries or "No such file or directory", re-create:
rm ~/.codex/skills/gws-*
for skill in ~/repos/gws-cli/skills/gws-*; do
  ln -s "$skill" ~/.codex/skills/$(basename "$skill")
done

# Restart Codex

Headless / CI environments — no browser for OAuth

Cause: Server environments don't have a browser for the OAuth redirect.

Fix: Authenticate on your Mac first, then export:

# On your Mac (with browser)
gws auth export --unmasked > ~/.config/gws/credentials-export.json

# On the headless machine
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials-export.json
gws drive files list   # works without browser

13. Basic Usage Examples

# List 10 most recent Drive files
gws drive files list --params '{"pageSize": 10}'

# Create a new spreadsheet
gws sheets spreadsheets create --json '{"properties": {"title": "Q1 Budget"}}'

# Preview a request without executing it (dry run)
gws drive files list --params '{"pageSize": 5}' --dry-run

# View the schema for any API method
gws schema drive.files.list

# Stream all results as NDJSON (newline-delimited JSON)
gws drive files list --params '{"pageSize": 100}' --page-all | jq -r '.files[].name'

# Create a Google Doc
gws docs documents create --json '{"title": "Meeting Notes"}'

# Create a calendar event
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Team Standup",
    "start": {"dateTime": "2026-03-20T09:00:00-05:00"},
    "end": {"dateTime": "2026-03-20T09:30:00-05:00"}
  }'

# Upload a file to Drive
gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

14. Example: Creating a Custom Codex Skill

This example creates a project-level skill that generates a technical architecture doc in Google Docs whenever you ask Codex to document your codebase.

Skill directory structure

Inside your project repo:

your-project/
  .agents/
    skills/
      generate-arch-doc/
        SKILL.md

SKILL.md

A skill is just a folder with a SKILL.md file. The file needs frontmatter with a name and description, then instructions below. The description is what Codex reads to decide whether to invoke the skill, so write it like a trigger condition — when to use it AND when not to.

---
name: generate-arch-doc
description: >
  Use this skill when the user asks to generate, create, or update
  architecture documentation for this project. Creates a Google Doc
  in Drive with the project's tech stack, directory structure, API
  endpoints, and key design decisions. Do NOT use for README updates,
  code comments, or non-architecture documentation.
---

## Steps

1. Read the project's `package.json`, `tsconfig.json`, and directory structure
   to identify the tech stack, dependencies, and project layout.

2. Scan `src/` for route files, middleware, database models, and service layers
   to map the application architecture.

3. Generate a structured architecture document with these sections:
   - Project Overview (name, purpose, tech stack)
   - Directory Structure (tree view with descriptions)
   - API Endpoints (method, path, description, auth requirements)
   - Database Schema (tables/collections, relationships)
   - Infrastructure (hosting, CI/CD, environment variables)
   - Key Design Decisions (patterns used and why)

4. Create the Google Doc:
   ```bash
   gws docs documents create --json '{"title": "Architecture Doc — <PROJECT_NAME> — <DATE>"}'

5. Capture the document ID from the JSON response.

6. Write content to the document using batchUpdate:

   gws docs documents batchUpdate \
     --params '{"documentId": "<DOC_ID>"}' \
     --json '{"requests": [{"insertText": {"location": {"index": 1}, "text": "<CONTENT>"}}]}'
   

7. Share the document link with the user.

Notes

• Always include the current date in the document title.
• If the project has a README.md, use it as additional context but don't duplicate it verbatim.

### Using the skill

Open your project in Codex, then either invoke it explicitly:

$generate-arch-doc Document the architecture of this project

Or implicitly — Codex will match on the description:

Generate an architecture document for this codebase and put it in Google Docs

### Skill design tips

- Keep each skill focused on one job.
- Write the description with clear scope boundaries ("Do NOT use for...").
- Prefer instructions over scripts unless you need deterministic behavior.
- Test prompts against the description to make sure it triggers correctly.
- Use the built-in `$skill-creator` inside Codex to generate skills interactively.

---

## 15. Example: Using Codex to Create and Email a Document

Once the `gws` skills are installed, you can ask Codex to chain multiple Workspace actions together conversationally. You don't need to write scripts — just describe what you want.

### The prompt

Open Codex in any project directory and type:

Read through this codebase and create a Google Doc summarizing the project — what it does, the tech stack, and any active TODOs you find in the code. Then email me the doc link at me@example.com with the subject "Project Summary".

### What happens

Codex will:

1. Scan the codebase using its built-in file reading
2. Invoke `$gws-docs` to create the Google Doc and write the summary into it
3. Invoke `$gws-gmail-send` to compose and send an email with the link

You review and approve each step as Codex proposes it.

### Why this matters

There's no script to write or maintain — it's a one-shot prompt. Codex handles the `gws` command syntax, JSON payloads, and document IDs for you. You can refine on the fly: "Add a section about the database schema" or "CC my cofounder."

### Prerequisite

You need the `gmail.modify` or `gmail.compose` scope. If you didn't include it during initial setup:

```bash
gws auth login -s drive,gmail.modify,sheets,calendar,docs,slides,tasks

16. Example: Using Codex to Schedule a Recurring Calendar Event

Another example of triggering a gws skill with a natural language prompt.

The prompt

Schedule a recurring weekly event on my Google Calendar called "Weekly Review"
every Monday at 9:00 AM Eastern for 30 minutes, starting next week.

What happens

Codex invokes $gws-calendar (or $gws-calendar-insert) and constructs the proper API call with recurrence rules, timezone, and duration. You approve the command before it executes.

Variations

You can get more specific:

Create a calendar event for tomorrow at 2pm called "Ship v1.0 Checklist" and
add a Google Doc link in the description.

Or chain with other skills:

Look at my Google Tasks and create a calendar event for each task that's due
this week, scheduled for 30 minutes each, spread across the mornings.

17. Example: Asking Codex to Research and Log Findings to a Sheet

This combines Codex's web search capability with the gws-sheets skill to build a lightweight research tracker.

The prompt

Search the web for the top 5 recent articles about AI agent frameworks. For each one,
log the article title, URL, publish date, and a one-sentence summary into a new
Google Sheet called "AI Agent Research — March 2026".

What happens

Codex will:

1. Use its web search tool to find relevant articles
2. Invoke $gws-sheets to create the spreadsheet
3. Use $gws-sheets-append to add each row of data

Making it repeatable

If you find yourself running this kind of prompt regularly, you have two options:

Option A — Save it as a Codex skill so you can invoke it with $research-to-sheet:

Create .agents/skills/research-to-sheet/SKILL.md in your project with the instructions baked in (see Section 14 for the skill format).

Option B — Use codex exec for non-interactive runs:

codex exec "Search for the top 5 AI agent framework articles from the past week \
and log them to a Google Sheet called 'AI Research — March 2026'."

codex exec runs non-interactively and streams results to stdout, which makes it suitable for automation.

Setting up a cron schedule

If you want this to run automatically (e.g., every Monday morning):

crontab -e

Add:

0 8 * * 1 /usr/local/bin/codex exec "Search for the top 5 AI agent framework articles from the past week and log them to a Google Sheet called 'AI Research'." >> /tmp/research-log.txt 2>&1

This gives you a self-updating research tracker without writing any scripts.

18. Updating & Maintenance

Updating the gws CLI

npm update -g @googleworkspace/cli

Updating the skills (if installed via git clone)

cd ~/repos/gws-cli
git pull
# Symlinks automatically pick up changes — no re-linking needed

Refreshing OAuth tokens

gws handles token refresh automatically. If your refresh token expires (rare — usually only if you revoke access or the token is inactive for 6+ months):

gws auth login -s drive,gmail.modify,calendar,sheets,docs,slides,tasks

Changing your GCP project

gcloud config set project new-project-id
gws auth setup

19. Key File Locations

Quick Reference Card

# Install
npm install -g @googleworkspace/cli

# Setup (automated)
gcloud config set project your-project-id
gws auth setup
gws auth login -s drive,gmail.modify,calendar,sheets,docs,slides,tasks

# Setup (manual — no gcloud)
# 1. Configure consent screen in Cloud Console
# 2. Create Desktop OAuth client in Cloud Console
# 3. Save client JSON to ~/.config/gws/client_secret.json
# 4. gws auth login -s drive,gmail.modify,calendar,sheets,docs,slides,tasks

# Verify
gws auth status
gws drive files list --params '{"pageSize": 3}'

# Install skills for Codex
mkdir -p ~/repos && cd ~/repos
git clone https://github.com/googleworkspace/cli.git gws-cli
mkdir -p ~/.codex/skills
for skill in ~/repos/gws-cli/skills/gws-*; do
  ln -s "$skill" ~/.codex/skills/$(basename "$skill")
done

# Export for headless/CI
gws auth export --unmasked > ~/.config/gws/credentials-export.json

# Update
npm update -g @googleworkspace/cli
cd ~/repos/gws-cli && git pull