gws-cli

Read-only Google Workspace CLI for goclaw skill integration.

Designed to be invoked via goclaw's secure_cli_run agent tool. Each invocation reads OAuth credentials from env vars, performs the operation, prints JSON, exits.

v0 commands

gws calendar list --days N --format json|text
gws gmail search --query Q --max-results N --format json|text

Drive subcommands deferred to v0.2.0 (Google drive.metadata.readonly is a restricted scope requiring app verification).

Env contract

Variable	Required	Purpose
GWS_REFRESH_TOKEN	yes	Per-operator OAuth refresh token (goclaw injects from secure_cli_user_credentials)
GWS_CLIENT_ID	yes	OAuth client ID for the goclaw GCP project
GWS_CLIENT_SECRET	yes	OAuth client secret
GWS_TOKEN_URI	no	Defaults to https://oauth2.googleapis.com/token

The CLI process exits after each invocation, so any in-memory access-token refresh by google-auth is discarded — no persistence, no race with the goclaw backend refresh worker.

Exit codes

Code	Meaning
0	success
1	generic error (HTTP error other than 401/403, parse failure, etc.)
2	env var missing
13	auth failed (HTTP 401 — refresh token revoked or invalid)
14	insufficient scope (HTTP 403 — user did not grant the required scope)

JSON output is a semver-bumped contract

Skill prompts depend on field shapes. Any field rename/removal in the output JSON is a major version bump (v1.0.0). Adding optional fields is a minor bump.

calendar list shape (v0.1.0)

[
  {
    "id": "string",
    "summary": "string",
    "start": "ISO8601 string or YYYY-MM-DD for all-day",
    "end": "ISO8601 string or YYYY-MM-DD for all-day",
    "attendees": [{"email": "string", "response": "accepted|declined|tentative|needsAction"}],
    "location": "string",
    "htmlLink": "string",
    "organizer_email": "string"
  }
]

gmail search shape (v0.1.0)

[
  {
    "id": "string",
    "threadId": "string",
    "from": "string (RFC 5322)",
    "subject": "string",
    "date": "string (RFC 2822)",
    "snippet": "string"
  }
]

Local dev

pip install -e ".[dev]"
pytest tests/

Docker

docker pull ghcr.io/dataplanelabs/gws-cli:0.1.0
docker run --rm \
  -e GWS_REFRESH_TOKEN=... -e GWS_CLIENT_ID=... -e GWS_CLIENT_SECRET=... \
  ghcr.io/dataplanelabs/gws-cli:0.1.0 calendar list --days=7

Releases

Tag-driven: push v* → CI builds + pushes to ghcr.io/dataplanelabs/gws-cli:<version> + :latest.

License

MIT.