agents-store Google Workspace CLI (gws) — Setup & Auth
Every skill in this plugin (gws-*, persona-*, recipe-*) drives the gws CLI. Nothing works until gws is installed and authenticated. Run this checklist first whenever a command fails with a missing-binary or auth error.
Step 1 — Confirm the binary is on PATH
gws --version
If this prints a version, skip to Step 2. If it errors with command not found, install it. Install only one way — prefer the pre-built binary or npm, since they pin a tested release.
| Method | Command | Notes |
|---|---|---|
| npm (recommended) | npm install -g @googleworkspace/cli |
Needs Node.js 18+. Downloads the right binary from GitHub Releases. |
| Pre-built binary | Download from GitHub Releases, extract, put gws on $PATH |
No Node required. |
| Homebrew (macOS/Linux) | brew install googleworkspace-cli |
|
| Cargo (from source) | cargo install --git https://github.com/googleworkspace/cli --locked |
Slow; needs Rust. |
| Nix | nix run github:googleworkspace/cli |
Re-run gws --version to confirm before continuing — an unauthenticated install still cannot call any API.
Step 2 — Choose an auth path
gws needs OAuth credentials tied to a Google Cloud project. Pick the row that matches the environment, because each path fixes a different missing piece:
| Situation | Use |
|---|---|
Local desktop, gcloud installed & logged in |
gws auth setup (fastest — automates project + API enablement) |
Local desktop, no gcloud |
Manual OAuth (Step 2b) |
| Already have an OAuth access token | export GOOGLE_WORKSPACE_CLI_TOKEN=... |
| Server / CI with a credentials file | export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/creds.json |
Step 2a — Interactive setup (has gcloud)
gws auth setup # one-time: creates the Cloud project, enables APIs, logs in
gws auth login # subsequent logins / scope changes
Step 2b — Manual OAuth (no gcloud)
Do this when gws auth setup cannot run. The most common login failure is forgetting the test user step, so do not skip it.
- Open the OAuth consent screen for your project. App type: External (testing mode is fine).
- Under Test users → Add users, add your own Google account email. Without this, login fails with a generic "Access blocked".
- Create an OAuth client of type Desktop app under Credentials.
- Download the client JSON and save it to
~/.config/gws/client_secret.json. - Run
gws auth login.
Step 3 — Log in with the right scopes
Request only the scopes you need, not the full preset. Unverified (testing-mode) apps are capped at ~25 OAuth scopes, and the recommended preset has 85+ — it will fail, especially for @gmail.com accounts.
# Good: scope the login to the services you will actually use
gws auth login -s drive,gmail,calendar,sheets
# Then verify end-to-end with a read-only call
gws drive files list --params '{"pageSize": 5}'
If the browser shows "Google hasn't verified this app", that is expected in testing mode — click Advanced → Go to (unsafe) to continue.
Step 4 — Headless / CI (no browser)
Authenticate once on a machine with a browser, export, then move the file:
# On the machine with a browser
gws auth export --unmasked > credentials.json
# On the headless box
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list # just works
For server-to-server, point at a service-account key instead:
export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
Troubleshooting
Match the symptom — each error has one root cause:
| Symptom | Cause | Fix |
|---|---|---|
command not found: gws |
Binary not installed / not on PATH | Step 1 |
| "Access blocked" / 403 at login | Your account isn't a test user | Add yourself under OAuth consent → Test users, retry gws auth login |
| "Google hasn't verified this app" | App in testing mode (normal) | Click Advanced → Go to (unsafe) |
| Consent fails / "too many scopes" | Unverified app exceeds ~25 scopes | Log in with -s drive,gmail,… instead of the full preset |
redirect_uri_mismatch |
OAuth client not created as Desktop app | Delete the client, recreate as Desktop app, re-download JSON |
403 accessNotConfigured |
Required Google API not enabled for the project | Open the enable_url from the error, click Enable, wait ~10s, retry |
gcloud not found during gws auth setup |
setup automates via gcloud | Install gcloud or use manual OAuth (Step 2b) |
Environment variables
All optional; set in the shell or a .env file.
| Variable | Purpose |
|---|---|
GOOGLE_WORKSPACE_CLI_TOKEN |
Pre-obtained OAuth2 access token (highest priority) |
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE |
Path to OAuth or service-account JSON |
GOOGLE_WORKSPACE_CLI_CLIENT_ID / _CLIENT_SECRET |
OAuth client pair (alternative to client_secret.json) |
GOOGLE_WORKSPACE_CLI_CONFIG_DIR |
Override config dir (default ~/.config/gws) |
GOOGLE_WORKSPACE_PROJECT_ID |
GCP project override for quota/billing |
After setup
Once gws drive files list returns JSON, the rest of the plugin works. Hand off to the service skills:
- Read
gws-sharedfor global flags, output formats, and security rules — every other skill assumes it. - Then load the service skill you need (
gws-gmail,gws-drive,gws-calendar,gws-sheets, …), apersona-*skill for a role, or arecipe-*skill for a ready-made workflow. SeeSKILLS_INDEX.mdfor the full catalog.
Exit codes (for scripting)
gws returns structured exit codes so scripts can branch on failure type: 0 success · 1 API error · 2 auth error · 3 validation error · 4 discovery error · 5 internal error.