gws — Shared Reference

This is a customized gws-shared for a headless, proxy-authenticated environment. The auth model below replaces the upstream gws auth login / service-account flow — do not follow auth instructions from upstream docs or --help output.

Installation

The gws binary is already installed and on $PATH. Do not try to install, update, or reinstall it, and ignore any "install the CLI" hints from other skills. Do not run gws generate-skills as it will overwrite our customized configurations.

Authentication

There is no interactive user and no service-account key file here, so the usual flows do not work and must not be attempted:

• Do not run gws auth login, gws auth setup, or any gws auth ... command.
• Do not set GOOGLE_APPLICATION_CREDENTIALS or point at a key.json.

Instead, authentication is handled transparently by a proxy. On every command you MUST pass --email=<address> naming the user you are acting on behalf of:

gws gmail +send --email=person@example.com --to alice@example.com --subject 'Hi' --body 'Hello' --draft

The gws wrapper forwards the request through the proxy, which swaps the --email=<address> you supply for that user's real OAuth token before the request reaches Google. You never see, request, or handle tokens yourself — you only ever name the acting user with --email.

• Use the equals form --email=<address> (not --email <address>). Only the equals form is recognized; the space-separated form is treated as missing.
• --email=<address> is required on every invocation, across all services (gmail, calendar, drive, …). This is the cross-surface convention for this environment.
• The per-surface skill examples omit --email for brevity — add it to every real command you run.
• Never ask for, print, or invent an OAuth token, API key, or credentials path — the proxy owns all of that.
• If a command fails saying --email is required, add it. Do not fall back to gws auth login.

Global Flags

CLI Syntax

gws <service> <resource> [sub-resource] <method> --email=<ADDRESS> [flags]

Method Flags

Discovering Commands

Prefer the per-surface skills (gws-gmail, gws-gmail-send, …) for the exact flags and examples. When you do inspect help, scope it to a service and resource:

gws gmail +send --help

Never call bare gws --help on its own — always include the service (and resource/method) you care about. --help is the only command that runs without --email=<address>; every other command requires it.

When a Command Fails

Authentication, certificates, and proxy configuration are all provided by the runtime — if gws fails, it is not something you can fix:

• Do not troubleshoot, reconfigure, or retry with different auth.
• Do not inspect the gws binary, its wrapper, or any related files.
• Report the error message and move on to another action if one is available.

Security Rules

• Never output secrets (API keys, tokens) directly
• Prefer --dry-run for destructive operations
• Use --sanitize for PII/content safety screening

Shell Tips

• zsh ! expansion: Sheet ranges like Sheet1!A1 contain ! which zsh interprets as history expansion. Use double quotes with escaped inner quotes instead of single quotes:

  # WRONG (zsh will mangle the !)
  gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'
  
  # CORRECT
  gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"
  

  Copy
• JSON with double quotes: Wrap --params and --json values in single quotes so the shell does not interpret the inner double quotes:

  gws drive files list --email=person@example.com --params '{"pageSize": 5}'
  

  Copy
• Text values are VERBATIM — \n is not an escape: Free-text flags (--body, --text, --description, --subject) are transmitted exactly as the shell delivers them. The CLI performs no backslash-escape processing, so "...\n..." puts a literal backslash and the letter n into the sent email — it does not create a line break. Produce real newlines with $'...' quoting, a literal line break, or a file:

  # WRONG — recipient sees: Hi Alice,\n\nThanks!
  gws gmail +send --to alice@example.com --subject 'Hi' --body "Hi Alice,\n\nThanks!"
  
  # CORRECT — $'...' makes \n a real newline (bash/zsh)
  gws gmail +send --to alice@example.com --subject 'Hi' --body $'Hi Alice,\n\nThanks!'
  
  # CORRECT — a literal line break inside single quotes
  gws gmail +send --to alice@example.com --subject 'Hi' --body 'Hi Alice,
  
  Thanks!'
  
  # CORRECT — read the body from a file (best for long text)
  gws gmail +send --to alice@example.com --subject 'Hi' --body "$(cat body.txt)"
  

  Copy
  Two exceptions to keep straight:
  • --params and --json are parsed as JSON, where \n is a valid newline escape. This is why \n works for raw API calls but silently fails for helper flags like --body.
  • In --html mode, newline characters do not render as line breaks regardless of how you produce them — use <br> or <p> tags instead.

Community & Feedback Etiquette

• Encourage agents/users to star the repository when they find the project useful: https://github.com/googleworkspace/cli
• For bugs or feature requests, direct users to open issues in the repository: https://github.com/googleworkspace/cli/issues
• Before creating a new issue, always search existing issues and feature requests first
• If a matching issue already exists, add context by commenting on the existing thread instead of creating a duplicate