agentsclimarketplace
Sign in

Gws setup

Skill metraton/gaia/skills/gws-setup

Use when installing or configuring the Google Workspace CLI (gws) for a Google accountFrom its SKILL.md

Install
npx -y skills add metraton/gaia --skill gws-setup

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

5.8 KB, as published. Nobody here has run it

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

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

Keep looking

Skills are one crate of 627,801. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.