| name | gws-auth |
| description | Google Workspace CLI authentication and environment setup. Handles gws and gws-auth installation, OAuth login, and token injection. This skill is a shared dependency for gws-sheets, gws-gmail, and other gws-based skills.
|
| license | Apache-2.0 |
| metadata | {"author":"swen","version":"0.1"} |
| compatibility | Requires gws (@googleworkspace/cli) ≥0.22.3 and gws-auth (github:planetarium/gws-auth) ≥0.4.0 |
Google Workspace Auth Skill
Installation
npm install -g @googleworkspace/cli https://github.com/planetarium/gws-auth/releases/download/v0.4.0/planetarium-gws-auth-0.4.0.tgz
Verify: gws --version && gws-auth --help
Authentication (gws-auth)
gws-auth is a dedicated OAuth CLI with embedded Client ID/Secret — no manual GCP credentials setup required.
Auth flow selection
gws-auth v0.4.0+ uses the authorization code flow (localhost redirect) which supports all Google Workspace scopes. Older versions (≤0.3.0) used the device code flow, which Google restricts to only 7 scopes (openid, email, profile, drive.appdata, drive.file, youtube, youtube.readonly). Gmail and Calendar scopes require v0.4.0+.
1. Check login status
gws-auth status 2>/dev/null && echo "AUTH OK"
If not logged in, ask the user to run the login command (requires one-time Google OAuth consent in a browser — the agent cannot run this directly):
gws-auth login
Default scopes are spreadsheets and drive.file. To request additional scopes:
gws-auth login --scope gmail.modify --scope spreadsheets --scope drive.file
When re-logging in, include all desired scopes (existing scopes are not automatically retained).
2. Export token before each call
export GOOGLE_WORKSPACE_CLI_TOKEN="$(gws-auth token)"
Available scopes
| Alias | Description |
|---|
spreadsheets | Google Sheets read/write (default) |
drive.file | Drive files created by the app (default) |
drive | Full Drive access |
drive.readonly | Drive read-only |
gmail.modify | Gmail read + write + label management |
gmail.readonly | Gmail read-only |
gmail.send | Gmail send-only |
calendar | Google Calendar read/write |
calendar.readonly | Google Calendar read-only |
docs | Google Docs read/write |
docs.readonly | Google Docs read-only |
Full list: gws-auth scopes
IMPORTANT: Token Optimization
Combine independent gws calls into a single Bash call with ;. Export the token once at the top:
export GOOGLE_WORKSPACE_CLI_TOKEN="$(gws-auth token)"
echo "=== Step 1 ===" ; gws <service> <command1> 2>&1
echo "=== Step 2 ===" ; gws <service> <command2> 2>&1
Discover commands
gws --help
gws schema <service.resource.method>
gws <service> <command> --dry-run
