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 account scope bug)
• https://github.com/googleworkspace/cli/issues/181 (multi-account bug)