gws Workspace Operations

Operate a user's Google Workspace account through the gws CLI — one binary covering every Workspace API, built dynamically from Google's Discovery Service, with structured JSON output. It is open source (Apache-2.0) but not an officially supported Google product and is pre-v1: expect breaking changes and pin versions in production.

Preflight

Before the first gws call in a session:

gws auth status --format json

• auth_method: "oauth2" or service_account → proceed.
• auth_method: "none" → stop. Follow references/setup-guide.md with the user to install gws and complete OAuth. Never invent client IDs, client secrets, or tokens; OAuth setup requires real user actions in the Google Cloud Console.
• command not found → install: npm install -g @googleworkspace/cli (alternatives: brew install googleworkspace-cli, cargo, nix).

The stderr line Using keyring backend: keyring is informational, not an error. Parse stdout only.

Command Model

Two surfaces; prefer helper commands when one fits.

Helper commands (+ prefix, hand-written):

Discovery commands (full API surface):

gws <service> <resource> <method> --params '{"k":"v"}'   # query/path params
gws <service> <resource> <method> --json '{"k":"v"}'     # request body
gws schema gmail.users.messages.list                     # inspect any method
gws gmail --help                                         # live command list

• Message metadata: request format: "metadata" plus metadataHeaders: ["Subject","From","Date"]; body parts are base64url in payload.body.data / payload.parts.
• Gmail search uses standard q operators (is:unread, newer_than:7d, after:2026/07/01 before:2026/07/08).
• Useful flags: --format json|table|yaml|csv, --page-all (NDJSON pagination), --output <path> (binary download), --upload <path>.

Safety Gates

• Read freely. list/get/triage/agenda/read need no confirmation.
• Confirm externally visible actions. Before gmail +send/+reply/+forward, chat +send, or creating calendar events that invite guests, restate the recipients, subject, and body summary; execute only after explicit approval.
• Confirm destructive actions. Deleting mail, Drive files, or events, and modifying existing events or documents, require explicit approval with the target ID shown.
• Least privilege. Request only the scopes the task needs during gws auth login; start read-only and expand. Never print credentials, tokens, or ~/.config/gws/ contents into chat output.
• Timezone: +agenda uses the Google account timezone; pass --timezone explicitly when the user expects another zone.

Troubleshooting

References

• references/setup-guide.md — from-zero install and OAuth setup: GCP project, consent screen, Desktop client, the secret-visible-once policy, test users, headless/CI credentials, and service accounts. Read it whenever gws auth status is not oauth2 or the user asks to install gws.