# Google Workspace Setup > One-time setup for gws: install, OAuth, scopes, auto-approve. - Skill: `lilac-labs/google-workspace-setup` (Agent Skill) - Install (CLI): `npx skillmds@latest add lilac-labs/google-workspace-setup` - Raw SKILL.md: https://api.skillmd.com/api/skills/lilac-labs/google-workspace-setup/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - License: MIT - Author: lilac-labs (https://skillmd.com/u/lilac-labs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lilac-labs/google-workspace-setup --- # Google Workspace Setup One-time onboarding for the Google Workspace skills (`google-gmail`, `google-calendar`, `google-drive`, `google-docs`, `google-sheets`, `google-meet`, `google-forms`). Installs `gws` and `gcloud`, signs the user into their own Google Cloud project, enables the Workspace APIs, captures an OAuth Desktop client through the inline Connect form, and completes `gws auth login`. The OAuth client lives in the user's own GCP project. The Client ID and Client Secret are captured through the inline Connect form (`request_connector` tool) and stored in Gini's encrypted secret store — never write them to chat or logs, and never write `client_secret.json` to disk. This skill is idempotent — re-running it re-verifies the install and lets the user widen scopes. **Provisioning vs signing in.** The work splits in two: **provisioning** (install, `gcloud auth login`, project, APIs, `request_connector`) runs **once**, ever; **signing in** (`gws auth login`) runs again whenever the user's `gws` session expires. `gcloud` is *only* ever needed for provisioning — never for a re-auth. Step 0 decides which case you're in. ## The Flow This is the **exact first-time sequence** (Step 0 short-circuits the already-signed-in and stored-client cases before you reach it). Within the first-time flow do not branch into shortcuts, do not pre-ask whether they have an existing OAuth client, do not list completed actions retrospectively. Status messages are action-oriented: what the user must do *next*. 1. The user asks Gini to do a Workspace thing (read mail, check calendar, share a Drive file, etc.). 2. Confirm setup with the user. 3. Install `gws` and `gcloud` silently in the background. 4. Run `gcloud auth login`, which pops up the user's default browser for sign-in. 5. After they sign in, create the Cloud project and enable the seven Workspace APIs in the background. 6. Send a single chat bubble with the last-step instructions (two Cloud Console URLs) and call `request_connector` — the inline form renders below the bubble. 7. After the user pastes the credentials and clicks **Save**, ask for a tag for this account and call `skill_run google-account-login`, which pops up the user's default browser for OAuth consent and registers the tagged account. 8. After they sign in, the original ask resumes. ## Step 0 — What state are we in? There are three states. Decide which one you're in **in this order** before doing anything else — each later step is only needed when the earlier check fails. In short: **already signed in? → else is the OAuth client stored? → else obtain it.** **(a) Already signed in.** If the user just wants to use Workspace, first check whether a registered Google account already has a live session. The "Connected Google accounts" block lists registered accounts; confirm one is valid with `gws auth status` (against that account's `configDir`) — a `token_valid: true` result means you're set. If so, **you're already set up**: skip the rest of this skill and resume the user's original ask. (If the user explicitly wants to connect *another* account, see "Adding another account later".) **(b) Not signed in, but the OAuth client is already stored.** Call `list_connectors` and look for a connector named `google-workspace-oauth`. If it exists, the OAuth client is already provisioned — **skip all provisioning**: do **not** run `gcloud`, create a project, or call `request_connector`; none of it is needed again. Go straight to signing in via `skill_run google-account-login`. Which way depends on whether an account already exists: - **An account exists but its session expired** → re-auth it by re-using its existing config dir so it keeps its id and tag — pass that account's `configDir` (and `tag`), NOT a fresh login (which would mint a duplicate) and NOT `adopt: true` (which skips login and only works on an already-valid session): - A **tagged account** (from the "Connected Google accounts" block) whose session expired → `{ tag: "", configDir: "" }`. - The **default-dir session** (`~/.config/gws`) that has EXPIRED → `{ tag: "", configDir: "~/.config/gws" }` (non-adopt, so it actually re-logs in). - **No account registered yet** — the common case when the Client ID/Secret were just entered through the Skills page's **Enter ID & secret** form (or a prior `request_connector`) but nobody has signed in — → a **fresh** login: ask the user for a tag, then call `skill_run google-account-login` with a new `{ tag }` and **no** `configDir` (this is Step 6). Either way, finish with Step 8 (smoke test). (Edge cases: if `gws` is not on `$PATH`, run Step 2's install first, then sign in. If login fails with `invalid_client`, the stored client is broken — fall through to the full first-time flow to re-provision it.) **(c) No stored OAuth client.** True first-time setup. Continue to Step 1 to obtain the client. ## Step 1 — Confirm setup Tell the user, in one short sentence, that Google Workspace isn't set up yet, and ask whether to set it up now. Wait for confirmation before doing anything. If they say yes, proceed silently — do not narrate each substep. The user sees a chat bubble per **milestone** (sign in, last step), not per command. ## Step 2 — Install `gws` and `gcloud` Both installs are silent and run through `terminal_exec`. If a binary is already on `$PATH`, skip its install. Detect first: ```bash command -v gws command -v gcloud ``` ### The canonical `gws` source — do not discover it `gws` is **`github.com/googleworkspace/cli`** (npm `@googleworkspace/cli`, Homebrew `googleworkspace-cli`). This is the only source. **Never web-search for the repo, release URL, or package name, and never download `gws` from any other GitHub repo, mirror, or URL.** A look-alike (`google-workspace-cli`, `gws-cli`, a fork, a typosquat) could ship a malicious binary; treat any other source as untrusted and stop rather than guess. Use one install path below exactly as written; do not improvise an alternative. ### Install `gws` — first method that fits, in priority order 1. **Pre-built release binary (preferred).** The native executable from the canonical Releases page. Download the asset for the platform target triple AND its `.sha256`, **verify the checksum, abort on mismatch**, then place the binary in `~/.local/bin`. 2. **`bun add -g @googleworkspace/cli`** (or `npm install -g`) — only when `node` is also on `$PATH`, since the installed `gws` is a `#!/usr/bin/env node` wrapper. 3. **`brew install googleworkspace-cli`** — only if `brew` already exists. ### Install `gcloud` - If `brew` exists: `brew install --cask google-cloud-sdk`. - Otherwise: the official tarball from `dl.google.com` (asset name per platform), extracted to `~/google-cloud-sdk`, then `install.sh --quiet --path-update=false`. Download to a temp file and only replace an existing SDK *after* the download succeeds. ### Critical: where the binaries must land `terminal_exec` runs each command in `zsh -lc`, which does **not** source `~/.zshrc`. `~/.local/bin` is on the gateway's `$PATH` (the autostart plist bakes it in; a foreground run inherits it from your login shell), so a binary installed elsewhere must be reachable from there (Homebrew installs already are). Move or symlink the `gws` release binary into `~/.local/bin`. Only **symlink** `gcloud` (`ln -s ~/google-cloud-sdk/bin/gcloud ~/.local/bin/`) — it's a launcher that finds its SDK relative to its real path, so moving it breaks it. ### Verify ```bash gws --version gcloud --version ``` **Do not thrash.** When a method fails, move to the **next method in the list once**, not back to the same dead end. Specifically: - Do **not** try to install Homebrew — its installer requires `sudo`, which an unattended agent cannot drive. - Do **not** probe for an absent brew, open a PTY for an interactive installer, or web-search for an install command. If every `gws` method fails (or both `gcloud` paths fail), STOP and tell the user verbatim what failed plus the single command to run manually for their platform, then wait. ## Step 3 — Sign in with `gcloud` ```bash gcloud auth login ``` This opens the user's **default browser** to Google's OAuth consent page. They sign in there. The command returns when the user completes consent. If `gcloud auth list` already shows an active account, ask once: "gcloud is signed in as ``. Use this account?" — proceed on confirmation. Otherwise run `gcloud auth login` straight through. ## Step 4 — Reach a Cloud project with the seven APIs enabled The goal of this step is a single value, ``, that names a Cloud project the active gcloud account owns AND in which the seven Workspace APIs are enabled. Every later step substitutes that string into URLs and `gcloud --project=` flags. **Invariants for this step and every later `gcloud` call:** - Pass `--project=` explicitly on every `gcloud` command that accepts it. Don't rely on `gcloud config get-value project`; its value can carry over from an unrelated shell or a prior failed run, which is exactly how the wrong-project `PERMISSION_DENIED` failure happens. - Treat `` as a value you discover, not a value you write. Read it from the output of `projects list` or `projects create`, then thread it through. - If the user named a specific project earlier in this chat ("use my work project `acme-data-1234`"), use that as `` and skip straight to 4c. Don't second-guess by listing or creating. ### 4a. Look for an ACTIVE Gini-managed project first ```bash gcloud projects list --filter="projectId:gini-workspace-* lifecycleState:ACTIVE" --format="value(projectId)" ``` The filter is on **project ID prefix**, which we control — not display name, which collides freely. Every project this skill creates has an ID starting with `gini-workspace-`. If the command returns one or more IDs, pick the first as `` and skip ahead to 4d. A prior setup run already provisioned it; making another would just leave orphans. ### 4b. Otherwise, undelete a recently-deleted one Google retains deleted project IDs in `DELETE_REQUESTED` state for ~30 days. During that window the name is reserved (so creating with the same ID fails with `ALREADY_EXISTS`) but the project can be restored with one call. Check before creating: ```bash gcloud projects list --filter="projectId:gini-workspace-* lifecycleState:DELETE_REQUESTED" --format="value(projectId)" ``` If this returns one or more IDs, pick the most recent and undelete it: ```bash gcloud projects undelete ``` Undelete is a single API call — it does NOT count against the per-minute project-create write quota the way `gcloud projects create` does, so this also avoids `RATE_LIMIT_EXCEEDED` during heavy testing. Most enabled APIs survive the undelete, but treat that as best-effort — 4d will re-enable any that didn't. Skip ahead to 4d once undelete succeeds. (Service Usage takes 30-90 s to re-recognize the project after undelete; 4d's `services enable` retries internally so it tolerates the gap.) ### 4c. Otherwise, create a fresh one The bare ID `gini-workspace` is almost always globally claimed — don't waste an attempt on it. Derive a deterministic, account-scoped suffix from the gcloud account so re-runs converge instead of accumulating projects: ```bash gcloud config get-value account # → something like "shelden@lilaclabs.ai" ``` Take the part before `@`, lowercase, and strip to `[a-z0-9-]`. The project-ID cap is 30 chars; `gini-workspace-` is 15, so truncate the suffix to 15 chars if needed. ```bash gcloud projects create gini-workspace- --name="Gini Workspace" ``` If even that ID is taken AND no DELETE_REQUESTED match was found in 4b (rare — only when a different user with the same email local-part already claimed it globally), append a 4-char random tiebreaker. `` is whichever ID succeeded. If `gcloud projects create` errors with `RATE_LIMIT_EXCEEDED` for `cloudresourcemanager.googleapis.com.write_requests`, the user has burned through Google's per-account project-create quota (usually from repeated testing). Surface the error verbatim and ask: "Google is rate-limiting project creates; the quota typically clears in ~10 minutes. Want to wait and retry, or do you have an existing Cloud project I can use? Reply with a project ID or 'wait'." Do not loop the create call. **Organization-restricted accounts.** If create instead errors with `PERMISSION_DENIED` and a message like `You do not have permission to create projects`, the account belongs to an organization (common on managed `@company` Google Workspace accounts) whose policy reserves project creation for admins. Accepting the Terms of Service will not change this. Surface the error verbatim and ask: "Your Google account can't create Cloud projects — your Workspace admin restricts that. Reply with an existing Cloud project ID I should use, or set Gini up with a personal @gmail.com account instead." Take a project ID as the new `` and resume from `projects describe` in 4d. ### 4d. Verify access, then enable the APIs `projects describe` is the cheapest probe that fails fast if the active account doesn't own `` — much better than learning it from `services enable`'s permission error after the model has already committed to a flow. ```bash gcloud projects describe --format="value(projectId)" ``` On success, enable the seven APIs (already-enabled ones are no-ops, which is fine when 4a reused an existing project): ```bash gcloud services enable \ gmail.googleapis.com \ calendar-json.googleapis.com \ drive.googleapis.com \ docs.googleapis.com \ sheets.googleapis.com \ forms.googleapis.com \ meet.googleapis.com \ --project= ``` Calendar's service ID is `calendar-json.googleapis.com` (not `calendar.googleapis.com`). If either 4d command errors with `PERMISSION_DENIED`, the active account doesn't own ``. Surface the error verbatim and ask the user briefly: "I don't have access to ``. Which project should I use?" Take their answer as the new `` and re-run from `projects describe`. Do not fall back to `gcloud config get-value project` to recover — that's the same stale value that produced the original failure. ## Step 5 — Last step: capture OAuth Desktop credentials This is the only step that requires the user to click in a browser. Send **one** chat bubble with the two Cloud Console URLs and call `request_connector` immediately after. The inline form renders below the bubble; the user pastes the Client ID and Client Secret and clicks **Save**. Construct the `reason` string as multi-line markdown with the URLs and click instructions. **Substitute `` with the actual project id from Step 4** — there is no runtime substitution. Use this exact format: ```text **Last step.** Complete the two Cloud Console pages below, then paste the credentials. **Step 1 — OAuth consent screen** (skip if already configured) https://console.cloud.google.com/apis/credentials/consent?project= - User Type: **External** - App name: **Gini Workspace** - Your email for support contact and developer contact - Save through Scopes (no scopes to add) - Add yourself as a **Test user** **Step 2 — Create an OAuth client** https://console.cloud.google.com/apis/credentials?project= - Click **Create Credentials → OAuth client ID** - Application type: **Desktop app** - Name it whatever (e.g. "Gini") - Click **Create** Then paste the **Client ID** and **Client Secret** below. ``` Then call: ```text request_connector { provider: "google-oauth-desktop", reason: " filled in>" } ``` Do NOT post a separate chat message before the tool call. Do NOT `open ` for either Console URL — let the user click from the bubble. Don't gate on "reply done" between the two pages — the form submission is what advances the flow. On Save, the connector is created with env bindings (`GOOGLE_WORKSPACE_CLI_CLIENT_ID`, `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET`), and the chat-task resumes at Step 6. ## Tagging the account Before login, ask the user for a short **tag** for THIS account — e.g. "personal", "work", "school". On first-time setup it's fine to ask "What should I call this account?" The tag labels the account everywhere (it's how Gini will later refer to it and how the user picks which account to use). Tags are unique across accounts. ## Step 6 — Sign in with `skill_run google-account-login` Now that the `google-workspace-oauth` connector exists, **delegate the login to the `google-account-login` skill** — do NOT run `gws auth login` from `terminal_exec` yourself. That skill's script gets the Client ID/Secret injected into its env, mints this account's own config dir, opens the user's browser to the consent screen, waits for them to finish, and registers the tagged account: ```text skill_run { skill: "google-account-login", script: "account-login", args: { tag: "", services: ["drive","gmail","calendar","docs","sheets","meet","forms"] } } ``` The script opens the user's default browser automatically and blocks until they complete consent — sign-in is human-in-the-loop, so don't type their email or password. It returns `{ ok, id, tag, email, configDir, scopes }` on success, or `{ ok: false, error }` on failure. On success, tell the user which account (by email + tag) is now connected, then go to Step 8. If `ok` is false, surface the `error` verbatim and act on it: - `"gws never printed the consent URL"` or a `gws auth login` failure → the user may have closed the browser without approving; just call `skill_run` again (idempotent). If it mentions `invalid_client`, the stored Client ID/Secret are wrong — re-run `request_connector` for `google-oauth-desktop` (Step 5). A `redirect_uri mismatch` means the OAuth client was created as Web type, not Desktop — re-create as Desktop and re-paste. - `"Login did not produce a valid session."` → the user didn't finish consent; offer to try again. **Always request every service we enabled APIs for in `services`, regardless of what the user originally asked.** The user enabled APIs for all seven Workspace products in Step 4, and Google's consent screen renders each scope as its own row with per-scope checkboxes (for unverified apps in testing mode) — the user picks which to grant *there*, not by us pre-filtering the `services` list. Narrowing `services` to just "calendar" because the user's first ask was a calendar question silently locks them out of Drive / Gmail / Docs / etc. for the rest of the session. ### When the user wants different scopes than the default Two cases warrant deviating from the all-seven-services default — pass them through the `args`: - **The user explicitly asks for a narrower or read-only grant** ("I only use Gmail, skip the rest" / "give Gini read-only access"). Trust them: pass `services: ["gmail"]` and/or `readonly: true`. - **The user is on a personal `@gmail.com` account AND wants the "full" Gmail scope** (`https://mail.google.com/`, which includes permanent delete). The default `recommended` preset will fail on unverified personal apps; pass the full scope URL(s) via `scopes` instead, which overrides `services`. ```text # Read-only across the user's chosen services args: { tag: "...", services: ["gmail","drive"], readonly: true } # Exact per-scope picks (full URLs) — for the rare case the user names a # specific scope shape service names can't express args: { tag: "...", scopes: ["https://www.googleapis.com/auth/gmail.readonly","https://www.googleapis.com/auth/drive"] } ``` `services` takes **service names**, not scope strings — `services: ["gmail.readonly"]` is silently dropped; use `scopes` with full URLs for that. Reference table of `services` name ↔ full scope URL (only useful when the user names a specific scope shape; the default is the full seven-service `services` list, not anything from this table): - **Gmail** — `-s gmail` ↔ `https://www.googleapis.com/auth/gmail.modify` (read + send + reply + label + draft; NOT permanent delete). Narrower: `.readonly` / `.send` / `.compose`. - **Gmail (full, incl. permanent delete)** — `--scopes "https://mail.google.com/"`. No `-s` shorthand. - **Drive** — `-s drive` ↔ `https://www.googleapis.com/auth/drive` (`.file`, `.readonly`, `.metadata.readonly` available as full URLs). - **Calendar** — `-s calendar` ↔ `https://www.googleapis.com/auth/calendar` (`.events`, `.readonly`, `.freebusy` available as full URLs). - **Docs** — `-s docs` ↔ `https://www.googleapis.com/auth/documents` (`.readonly` available). - **Sheets** — `-s sheets` ↔ `https://www.googleapis.com/auth/spreadsheets` (`.readonly` available as a full URL). - **Meet** — `-s meet` ↔ `https://www.googleapis.com/auth/meetings.space.created` (`.readonly` available). - **Forms** — `-s forms` ↔ `https://www.googleapis.com/auth/forms.body` (`.body.readonly`, `.responses.readonly` available). Never pass `--full` or the default `recommended` preset on a personal `@gmail.com` account — those expand to 80+ scopes including pubsub and cloud-platform, which an unverified app cannot grant. The seven-service list stays under the ~25-scope cap. ## Adding another account later When the user wants to connect an **additional** Google account (one OAuth client can authorize many accounts), there's no new project, connector, or `gcloud` work — the existing `google-workspace-oauth` connector / Cloud project is re-used. Just: 1. Ask the user for a **tag** for the new account ("What should I call this one?"). 2. If the Cloud app is still in testing mode, the new account's email must be a **Test user** on the OAuth consent screen, or consent will fail. Give them the consent-screen URL to add it (substitute the project id): `https://console.cloud.google.com/apis/credentials/consent?project=` 3. Call `skill_run google-account-login` with the new tag (NOT `adopt`): ```text skill_run { skill: "google-account-login", script: "account-login", args: { tag: "", services: ["drive","gmail","calendar","docs","sheets","meet","forms"] } } ``` This signs the second account into its own config dir and registers it alongside the first. ## Adopting the existing sign-in Use `adopt: true` ONLY to IMPORT an already-**valid** `~/.config/gws` session as a tagged account without a fresh login — e.g. the user had a pre-existing `gws` setup and you just want it on the account list. It never opens the browser, never touches `~/.config/gws`'s tokens, and **fails if that dir's session is not currently live**. ```text skill_run { skill: "google-account-login", script: "account-login", args: { tag: "", adopt: true } } ``` Do NOT use `adopt: true` to fix an **expired** default-dir session — adopt skips login, so it can't re-auth. To re-log-in the default dir, pass `configDir: "~/.config/gws"` (non-adopt) per Step 0's re-auth path. Rule of thumb: `adopt` = import a valid session; `configDir` = re-auth / target a specific existing dir with a real login. ## Step 7 — Stop the per-call approval prompt (optional) Every `gws` call goes through Gini's approval-gated `terminal_exec` tool. To stop the prompt firing on every invocation, patch the per-instance auto-approve list: ```bash curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \ -d '{"patterns": ["gws *"]}' \ http://127.0.0.1:/api/settings/auto-approve ``` Set `$TOKEN` from `~/.gini/instances//config.json` (the `apiToken` field). For finer-grained gating, list each product: ```json { "patterns": ["gws gmail *", "gws calendar *", "gws drive *", "gws docs *"] } ``` ## Step 8 — Smoke test A read-only call that exercises auth: ```bash gws drive files list --params '{"pageSize": 1}' ``` If that returns JSON without an auth error, the setup is complete. Resume the user's original ask (read mail, list calendar events, etc.). ## Rules 1. Walk this skill end-to-end on **first-time** setup. Do not skip to `request_connector` or the `google-account-login` skill without the install + project + APIs in place. The one exception is the **stored-client** path (Step 0 (b)): when the `google-workspace-oauth` connector already exists, `skill_run google-account-login` alone is the whole job — whether re-authing an expired account or doing the first sign-in for a freshly-stored client. `gcloud`, project creation, and `request_connector` are provisioning-only and must not re-run. 2. **Sign-in is a human-in-the-loop step.** Never attempt to type the user's email or password. `gcloud auth login` and the `google-account-login` script both open the default browser — wait for the command (or `skill_run`) to return. 3. **Capture credentials through the inline form, not files.** Always use `request_connector { provider: "google-oauth-desktop" }`. Never ask the user for a path to `client_secret.json`, never write a JSON file under `~/.config/gws/`, and never `cat` or echo the credentials back into chat. 4. **Enable all seven Workspace APIs in Step 4 regardless of which product triggered setup.** One `gcloud services enable` call covers them all; this lets the user pivot to another product later without re-running setup. 5. **Status messages are action-oriented and ungrouped.** Do not list "Installed gws, installed gcloud, signed in, created project, enabled APIs." The user sees a chat bubble per milestone (confirm setup, last-step form, done) — not a retrospective changelog. 6. **Fail gracefully.** If `gcloud` errors with `PERMISSION_DENIED` or `ALREADY_EXISTS`, surface the error verbatim and ask the user. If an install fails, STOP — do not retry in a loop, hand off to the user with the one-line manual command. 7. **The `services` you pass to `google-account-login` include every service we enabled APIs for in Step 4, not just the one the user happened to ask about.** Google's consent screen renders each scope as its own checkbox row in testing mode — the user picks there. Narrowing `services` based on the current request silently locks the user out of the other six surfaces; they'd have to re-run setup the next time they want anything else. The only time you narrow is when the user explicitly says so ("read-only," "Gmail only," etc.). 8. If the user is in a CI or headless environment, point them at the export flow (`gws auth export --unmasked > credentials.json` on a desktop machine, then `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=…` on the headless one). ## Manual Fallback If `gcloud` cannot be installed at all (uncommon — both macOS and Linux have a documented tarball install at https://docs.cloud.google.com/sdk/docs/install-sdk), hand off the Cloud Console flow to the user manually: 1. Tell them to open https://console.cloud.google.com/ and create a project named `gini-workspace`. 2. Enable the seven APIs at https://console.cloud.google.com/apis/library — Gmail, Calendar, Drive, Docs, Sheets, Forms, Meet. 3. Then resume from Step 5 (configure OAuth consent, create Desktop OAuth client, paste credentials into the inline form). For flags not shown here, run `gws auth --help` and `gws --help`.