/gws-setup

name: gws-setup
description: Use when installing or configuring the Google Workspace CLI (gws) for a Google account -- "instala gws", "configura el cli de Google Workspace", "conecta mi cuenta de Google", "set up gws", "install the Google Workspace CLI".

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 the `gws 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

• `gaia login start gcloud --account <email>` prints a link to open in the browser; no terminal needed (skill `cli-login`)
• 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 accou