/gws-setup

name: gws-setup
description: Use when installing or configuring the Google Workspace CLI (gws) for a Google account

GWS Setup

The gws CLI looks straightforward but breaks in subtle ways -- Google's OAuth flow has undocumented constraints that differ between personal and organizational accounts, and the gws tool itself has open bugs around scopes and multi-account. This procedure captures the working path and the traps discovered through real setup sessions, so you avoid the silent failures that waste hours.

**Prerequisites:** gcloud CLI installed, browser access for OAuth, interactive terminal for auth steps.

Procedure

1. Install gws binary

• Download latest Linux x86_64 from https://github.com/googleworkspace/cli/releases
• Place in `~/.local/bin/`, `chmod +x`
• Verify: `gws --version`

2. Add Google account to gcloud

• `gcloud auth login <email> --no-launch-browser` (interactive terminal required)
• This adds alongside existing accounts -- does NOT replace them
• After login, restore work account: `gcloud config set account <work-account>`

3. Create or select GCP project

• Check existing: `gcloud projects list --account=<email>`
• Create new: `gcloud projects create gaia-<name> --name="Gaia <Name>" --account=<email>`
• Naming: `gaia-<identifier>-personal` or `gaia-<identifier>-work`

4. gws auth setup

• `gws auth setup --project <project-id>`
• TRAP: When selecting scopes, DO NOT use presets ("Recommended" or "Read Only") -- they include organizational scopes that break for @gmail.com accounts

5. Scope selection (CRITICAL)

For safe scopes and blocked scopes by account type, read `reference.md` in this directory.

Known bug: gws issue #119 -- `gws auth login` unusable with personal @gmail.com when organizational scopes are included. Google returns `400: invalid_scope`.

6. OAuth consent screen (manual in browser)

• URL: `https://console.cloud.google.com/apis/credentials/consent?project=<project-id>`
• User Type: External | App name: gws CLI | Support email: the account email
• TRAP: Add the account as a Test User BEFORE attempting login
• Test Users section -> Add Users -> enter the email
• Without this, Google returns `403: access_denied` ("app not verified")

7. OAuth client (manual in browser)

• URL: `https://console.cloud.google.com/apis/credentials?project=<project-id>`
• TRAP: Application type must be **Desktop app** (NOT "Web application")
• Web application type causes `401: invalid_client`
• Download `client_secret_*.json` -> save to `~/.config/gws/client_secret.json`

8. gws auth login

• `gws auth login` -- opens browser for OAuth consent (interactive terminal required)
• If Google shows "app not verified" warning -> click "Advanced" -> "Go to gws-cli (unsafe)" -- safe for personal use

9. Verification

• `gws auth status` -- confirm token valid
• `gws gmail users messages list --params '{"userId":"me","maxResults":5}'` -- test Gmail
• `gws gmail users labels list --params '{"userId":"me"}'` -- test labels

10. Publish OAuth consent app to Production (stabilize tokens)

• URL: `https://console.cloud.google.com/apis/credentials/consent?project=<project-id>` -- the OAuth consent screen, surfaced in the current console under **APIs & Services -> OAuth consent screen -> Audience** (new "Google Auth Platform" layout: **Audience** page).
• Under **Publishing status**, click **PUBLISH APP** to move the app from **Testing** to **In production**, then confirm.
• WHY THIS MATTERS (the silent 7-day trap): while the app stays in **Testing**, Google issues refresh tokens that **expire after 7 days** whenever any requested scope goes beyond `name` / `email` / `profile` -- and Gmail scopes always do. The stored credential silently dies after a week, `gws auth status` starts failing, and the whole login must be redone. Publishing to **In production** removes the 7-day cap and stabilizes the token.
• Verification is NOT required to publish for personal single-user use. With sensitive scopes (`gmail.modify`) an unverified production app simply shows the same "Google hasn't verified this app" warning as Testing did -- proceed via **Advanced -> Go to gws CLI (unsafe)**. Verification is a separate Google review that removes the warning screen and is only needed for a public app serving *other* users' accounts, not your own.
• Traps that remain even in production (Google token policy): a refresh token also dies after **6 months of non-use**, on a **Google password change** while Gmail scopes are granted, or when the user revokes access. Recover any of these by re-running `gws auth login`.

11. Restore gcloud

• `gcloud config set account <original-work-account>`
• Verify: `gcloud config get account`

Multi-account (future)

gws supports multi-account via `gws auth login --account <email>`, `gws auth list`, `gws auth default <email>`, `gws --account <email> <command>`.

Known bug: issue #181 -- `--account` flag doesn't work correctly yet.

Anti-Patterns

• Using scope presets for personal @gmail.com -- causes `400: invalid_scope`
• Skipping Test User in OAuth consent screen -- causes `403: access_denied`
• Choosing "Web application" as OAuth client type -- causes `401: invalid_client`
• Leaving the OAuth consent app in **Testing** -- refresh tokens expire after ~7 days with Gmail scopes, forcing weekly re-auth. Publish to **In production** (step 10) to stabilize
• Forgetting to restore `gcloud config set account` after setup
• Including `admin.*`, `cloud-identity.*`, or `directory.*` scopes for personal accounts

Related Skills

• `gmail-policy` -- operational Gmail security (tiers, labels, no-delete rule)

References

• https://github.com/googleworkspace/cli
• https://github.com/googleworkspace/cli/issues/119 (personal account scope bug)
• https://github.com/googleworkspace/cli/issues/181 (multi-account bug)