streakyc/googleworkspacecli

gws-shared

gws CLI: Shared patterns for authentication, global flags, and output formatting.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/streakyc/googleworkspacecli --skill gws-shared

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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:

bash
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

FlagDescription
--email=<ADDRESS>Required. User to act on behalf of; the proxy swaps it for that user's OAuth token. Use the equals form.
--format <FORMAT>Output format: json (default), table, yaml, csv
--dry-runValidate locally without calling the API
--sanitize <TEMPLATE>Screen responses through Model Armor

CLI Syntax

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

Method Flags

FlagDescription
--params '{"key": "val"}'URL/query parameters
--json '{"key": "val"}'Request body
-o, --output <PATH>Save binary responses to file
--upload <PATH>Upload file content (multipart)
--page-allAuto-paginate (NDJSON output)
--page-limit <N>Max pages when using --page-all (default: 10)
--page-delay <MS>Delay between pages in ms (default: 100)

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:

bash
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:
bash
  # WRONG (zsh will mangle the !)
  gws sheets +read --spreadsheet ID --range 'Sheet1!A1:D10'

  # CORRECT
  gws sheets +read --spreadsheet ID --range "Sheet1!A1:D10"
  • JSON with double quotes: Wrap --params and --json values in single quotes so the shell does not interpret the inner double quotes:
bash
  gws drive files list --email=person@example.com --params '{"pageSize": 5}'
  • 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:
bash
  # 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)"

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

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills