---
name: google-workspace-gws-access
description: Access Google Workspace Admin Reports through the gws CLI with read-only auth. Use when logging in with the correct scopes, verifying saved credentials, troubleshooting missing admin.reports scopes, or exporting audit feeds to ndjson safely and repeatably.
---

# Google Workspace GWS Access

## Goal

Use this skill when the task is operational rather than analytical:

- authenticate `gws` with the right read-only scopes
- verify saved credentials and refresh-token health
- troubleshoot missing `admin.reports.*` scopes
- export Admin Reports feeds into a repeatable local folder layout

## Default Rules

- Use read-only scopes only unless the user explicitly requests broader access.
- Prefer the Admin Reports scopes:
  - `https://www.googleapis.com/auth/admin.reports.audit.readonly`
  - `https://www.googleapis.com/auth/admin.reports.usage.readonly`
- Verify scopes after login before trying to pull logs.
- Do not rely on manually pasted OAuth URLs.
- Treat `gws auth status` as the first truth source for whether the saved session is usable.

## Workflow

1. Confirm `gws` is installed and reachable.
2. Check saved auth with `scripts/check_gws_auth.sh`.
3. If required scopes are missing, run a fresh `gws auth login --scopes ...`.
4. Verify the reports API works with a minimal `activities.list` call.
5. Export data with `scripts/export_admin_reports.sh`.
6. If the CLI picker does not show `admin.reports.*`, bypass it with explicit `--scopes`.

## Known Pitfalls

- The interactive scope picker may not show `admin.reports.*`.
- Reusing a stale localhost callback URL in the browser breaks the OAuth flow.
- Cached credentials may exist but still lack the required report scopes.
- Changing the scope set usually requires a fresh login.

## Script Entry Points

- `scripts/check_gws_auth.sh`
- `scripts/export_admin_reports.sh --start <iso> --end <iso> --output-dir <dir>`

## Resources

- `references/required-scopes.md`
- `references/gws-command-recipes.md`
- `references/auth-troubleshooting.md`
- `references/export-layout.md`