Google Workspace

Google Workspace via gws

gws (install: npm install -g @googleworkspace/cli; this skill targets 0.22.x) speaks every Workspace API the user is likely to ask about — Drive, Docs, Sheets, Gmail, Calendar, Chat, Tasks, Slides, Keep, Forms, Apps Script, Meet. It is a community CLI ("not an officially supported Google product"). It wraps the REST APIs so you don't hand-roll curl, but it does not bundle credentials: you must configure an OAuth client or service account first, then authenticate.

When to use this skill

Any user request that names a Google Workspace surface:

• "read this Drive file", "list my Drive folder", "share this doc"
• "create a Google Doc with…", "update this sheet", "append a row"
• "send an email", "draft a Gmail reply", "check my inbox for…"
• "what's on my calendar", "schedule a meeting"
• "post to this Chat space"

Do NOT shell out to curl against the raw Workspace REST APIs — gws already wraps them and handles pagination, retries, and JSON parsing.

Auth

First, always: try the pre-injected token

Before any OAuth client, service account, or login dance, check for a pre-injected access token. When the user has used "Connect Workspace" in the web UI, the GOOGLE_WORKSPACE_CLI_TOKEN secret is auto-injected into every bash command and is gws's highest-priority auth source — no OAuth client, no login, no loopback bridge. Don't ask, don't inspect the environment, just probe with a cheap read against the surface you need:

bash(command="export GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/workspace/lha/config/gws GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file && gws gmail messages list --params '{\"maxResults\": 1}'")

• If it returns data, you're done — the token works. Proceed with the task.
• If it 403s / scope error, the token is valid but the user didn't grant this surface (or only read-only). The "Connect Workspace" flow is per-surface (drive / gmail / calendar / sheets / docs / chat / tasks / slides / keep / script / meet / forms) × read-only|read-write, read-only by default — ask the user to reconnect with the surface (or read-write) you need; don't start a login dance.
• If it 401s / "not logged in", the token is truly missing or lapsed (it's a ~1h token, no refresh) — then fall back to the OAuth-client login below, or ask the user to re-click "Connect Workspace".

Do NOT trust gws auth status here. With the env token it reports auth_method: none / credential_source: token_env_var even though reads succeed — a real read is the only reliable check. Skipping the probe and jumping to gws auth login is the mistake to avoid: it drags the user through a browser-redirect bridge that the already-present token makes unnecessary.

Otherwise: configure an OAuth client

gws has no embedded OAuth client. gws auth login fails until one of these is in place:

1. client_secret.json — drop an OAuth client secret file into the gws config dir. Preferred in the sandbox — see "Creating the OAuth client" below. Keep that dir on /workspace (next section) so it survives.
2. Env vars — set GOOGLE_WORKSPACE_CLI_CLIENT_ID and GOOGLE_WORKSPACE_CLI_CLIENT_SECRET.
3. Service account — set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json. No gws auth login step is needed in this mode; calls authenticate directly with the key (use for fully unattended automation, no user present).
4. gws auth setup — provisions a GCP project + OAuth client for you, but renders a full-screen interactive TUI that can't be driven from bash (no keyboard input). Don't use it headless — create the client_secret.json by hand (option 1) instead.

Creating the OAuth client (one-time)

When building the OAuth client yourself (via gcloud or the Cloud console):

• Choose the "Desktop app" client type, not "Web application". gws auth login listens on a random loopback port; a Web-app client rejects that with Error 400: redirect_uri_mismatch. Desktop-app clients accept loopback.
• For a corporate Workspace org, set the consent-screen audience to Internal. An internal-audience client clears the Context-Aware Access / "Account restricted" block that the default gcloud OAuth client trips on.
• The client_secret.json's project_id must be a project the authenticating account may use — otherwise calls fail with the quota-project 403 (see Failure handling).

Config dir + keyring (sandbox gotchas)

Set both on every gws command — each bash call is a fresh non-login shell, so exports don't carry over between calls:

export GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/workspace/lha/config/gws
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

• GOOGLE_WORKSPACE_CLI_CONFIG_DIR — relocates the config dir (which holds client_secret.json, the token, and the encryption key) onto /workspace. The default ~/.config/gws is not migrated on runtime upgrades, so without this you'd redo the browser login after the next upgrade.
• GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file — there's no OS keyring headless; the file backend writes the key into the config dir (hence also on /workspace).

Authenticating

With an OAuth client configured, authenticate with:

bash(command="gws auth login --readonly")  # read-only scopes (start here)
bash(command="gws auth login")             # all default scopes
bash(command="gws auth login -s drive,gmail,sheets")  # limit the picker
bash(command="gws auth login --scopes <comma,separated,scopes>")

Start with read-only scopes (--readonly) — least privilege. Add write scopes only when the task actually needs to write, by re-running gws auth login --scopes <…> for the specific surface; Google's incremental consent merges the new scope with what's already granted, so you never over-grant up front.

gws auth login is loopback-browser only — it opens a browser and waits on a local listener for the OAuth redirect. There is NO device-code / paste-a-code flag.

Completing the loopback flow headless. It does work in the sandbox — you bridge the redirect by hand. The browser opens on the user's machine, but the listener is inside the container, so you relay the redirect URL across. The URL appears in one turn and the user pastes back in a later turn, so use the cross-turn process pipeline (process(action='spawn', ...) + process):

process(action='spawn', command="export GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/workspace/lha/config/gws GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file && gws auth login")
# read the printed auth URL, surface it VERBATIM to the user, then wait
process(action='poll', session_id=<id>)

1. The user opens the auth URL, consents, and their browser lands on a http://localhost:<port>/?code=...&scope=... page that won't load (the listener is in the sandbox, not on their machine). Ask them to copy that full redirect URL from the address bar and paste it back.
2. curl that exact URL from inside the sandbox to hand the code to the waiting listener, which completes the exchange and writes the token:

   bash(command="curl -s 'http://localhost:<port>/?code=...&scope=...'")

   The backgrounded gws auth login then finishes.

(localhost is on Layer A's allowlist, so this curl isn't gated.) For fully unattended jobs where no user is present to paste the redirect, use a service account instead — the loopback bridge needs a live user.

Check state any time with bash(command="gws auth status").

Command form

gws <service> <resource> [sub-resource] <method> [flags]

Query parameters are passed as JSON via --params; request bodies via --json. Wrap both in single quotes so the shell preserves inner double quotes:

gws drive files list --params '{"pageSize": 5, "q": "trashed=false"}'
gws drive files create --json '{"name": "notes.txt"}' --upload notes.txt

Several common operations also have ergonomic helper commands (prefixed +) that take plain flags instead of JSON — e.g. gws sheets +read, gws sheets +append, gws gmail +send, gws drive +upload.

Useful global flags: --format json|table|yaml|csv (json default), --dry-run (validate without hitting the API), --page-all (auto-paginate to NDJSON), -o/--output <path> (save binary responses), --sanitize <template> (screen responses through Model Armor).

Discovery — don't guess params

bash(command="gws drive --help")                 # resources + methods
bash(command="gws schema drive.files.list")      # params, types, defaults

gws schema <service>.<resource>.<method> prints the exact param shape for a method. Run it (or gws <service> --help) whenever you're unsure of a flag — it's authoritative for the installed version.

Prefer the official per-surface skills for depth

The tables below are a quick reference, not the full surface. gws ships maintained per-surface skills upstream — gws-drive, gws-gmail, gws-sheets, gws-calendar, gws-chat, gws-people, gws-slides, gws-tasks, plus curated recipes — that cover the less-common methods this file doesn't. For anything beyond the common operations, install the relevant skill into the workspace and read it (note the path the command prints):

bash(command="npx -y skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive")

Swap gws-drive for the surface you need. These are version-pinned docs, so when a skill and the installed binary disagree, gws schema <service>.<resource>.<method> wins — it reflects the gws actually on PATH.

Common operations

Confirm the exact params with gws schema … before write/delete calls — the shapes above are the common cases, not an exhaustive contract.

Keep caveat: the Google Keep API is restricted to Workspace Enterprise domains via service-account domain-wide delegation — an ordinary Connect-Workspace access token will likely 403 on gws keep … regardless of the granted scope. If it does, tell the user it's an API restriction, not a missing grant.

Under a routine, the Google token is present only if you declared its secret name (GOOGLE_WORKSPACE_CLI_TOKEN) in the routine's secrets:.