Dbochman/gws-shared

gws — Shared Reference

Installation

The gws binary must be on $PATH. See the project README for install options.

Authentication

Credentials are AES-256-GCM encrypted at ~/.config/gws/. Auth requires a browser (OAuth) — auth locally, then scp credentials + .encryption_key + accounts.json to headless machines.

DANGER: gws auth logout without --account <email> NUKES ALL accounts. Always use gws auth logout --account <email> for per-account removal.

Accounts

| Account | Owner | Flag | |---------|-------|------| | [email protected] | Dylan | Default (no flag needed) | | [email protected] | Julia | --account [email protected] | | [email protected] | Dylan (spam) | --account [email protected] | | [email protected] | OpenClaw | --account [email protected] |

When Dylan asks about "my email/calendar/drive", use default. When he says "Julia's", use her account.

Global Flags

| Flag | Description | |------|-------------| | --format <FORMAT> | Output format: json (default), table, yaml, csv | | --dry-run | Validate locally without calling the API | | --sanitize <TEMPLATE> | Screen responses through Model Armor |

CLI Syntax

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

Method Flags

| Flag | Description | |------|-------------| | --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-all | Auto-paginate (NDJSON output) | | --page-limit <N> | Max pages when using --page-all (default: 10) | | --page-delay <MS> | Delay between pages in ms (default: 100) |

Account selection: --account vs GOOGLE_WORKSPACE_CLI_ACCOUNT

The CLI has two ways to pick an account, and they don't behave identically:

• --account <email> — works on the helper subcommands (+agenda, +insert, +inbox, etc.) and on gws auth ....
• GOOGLE_WORKSPACE_CLI_ACCOUNT=<email> — works on EVERYTHING, including the raw API resource calls (calendar events list, gmail users messages get, calendar calendarList list, etc.).

Calling raw API endpoints with --account may return 401 "No credentials provided" even though the account is fully authenticated — the flag isn't plumbed through to those code paths in v0.4.4. Set the env var instead:

[email protected] gws calendar events list \
  --params '{"calendarId":"primary","maxResults":3}'

For scripts that hit raw endpoints, export the var once at the top instead of passing --account per call.

Transient auth errors — retry once

The gws CLI occasionally returns this error mid-token-refresh:

{"error":{"code":401,"message":"<service> auth failed: Failed to get token","reason":"authError"}}

This is a race, not a real auth failure: the local token cache is being rewritten while the API call reads it. Distinguishable from real auth failures because real ones say Access denied. No credentials provided. Run gws auth login instead.

When you see "Failed to get token", retry once after sleeping 3-5 seconds before reporting auth failure. A second call almost always succeeds.

out=$(gws calendar +agenda --days 7 2>&1)
if echo "$out" | grep -q '"Failed to get token"'; then
  sleep 5
  out=$(gws calendar +agenda --days 7 2>&1)
fi
echo "$out"

Hit on 2026-05-02 — Dylan's morning briefing fired at 08:00 ET, which was the exact moment the token cache file was being rewritten. The agent saw the 401, didn't retry, and reported "Calendar auth is failing" in the briefing. Manual retry 30 minutes later worked first try.

Security Rules

• Never output secrets (API keys, tokens) directly
• Always confirm with user before executing write/delete commands
• Prefer --dry-run for destructive operations
• Use --sanitize for PII/content safety screening

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