Google Workspace Auth (gws auth)

gws auth manages OAuth2 authentication for all Google Workspace services.

Disclaimer: gws is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.

Dependency Check

Before executing any gws command, verify the CLI is installed:

gws version

If not found, install: go install github.com/omriariav/workspace-cli/cmd/gws@latest

Quick Command Reference

Service-Account Modes (v1.43.0+)

Besides the default interactive OAuth flow, gws supports two explicit service-account modes via authmode (GWSAUTH_MODE or config file). Modes are mutually exclusive and validated fail-closed with actionable errors; key material is never persisted, printed, or echoed.

# Domain-wide delegation (requires DWD enabled for the service account
# and the scopes authorized in the Admin console)
export GWS_AUTH_MODE=service-account-dwd
export GWS_SERVICE_ACCOUNT_KEY_FILE=~/keys/sa.json
export [email protected]
gws gmail list   # runs as the impersonated user, no login needed

# Chat app auth (events subscriptions only)
export GWS_AUTH_MODE=service-account-app
export GWS_SERVICE_ACCOUNT_KEY_FILE=~/keys/chat-app-sa.json
gws events subscriptions create --target //chat.googleapis.com/spaces/AAA ...

Notes:

• gws auth login fails fast in service-account modes (no login needed);

gws auth status reports the configured mode instead of token state.

• Incomplete or mixed configuration is rejected: DWD without

impersonateuser, app mode with impersonateuser, or OAuth mode with leftover service-account settings all produce clear errors.

First-Time Setup

If you haven't set up Google Cloud credentials yet, see the detailed setup guide: [Setup Guide](references/setup-guide.md)

Quick summary:

1. Create a Google Cloud project
2. Enable the required Workspace APIs
3. Create OAuth 2.0 credentials (Desktop app type)
4. Set credentials via environment variables or config file
5. Run gws auth login

Detailed Usage

status — Check authentication status

gws auth status

Shows whether you're authenticated, the current user email, and token expiry info.

login — Authenticate with Google

gws auth login [flags]

Flags:

• --client-id string — OAuth client ID (overrides env/config)
• --client-secret string — OAuth client secret (overrides env/config)
• --services string — Comma-separated services to authorize (e.g. gmail,calendar,chat). Omit for all scopes.

Opens a browser for Google OAuth consent. The token is stored at ~/.config/gws/token.json.

Available services: gmail, calendar, drive, docs, sheets, slides, tasks, chat, forms, contacts

Credential sources (in priority order):

1. Command-line flags (--client-id, --client-secret)
2. Environment variables (GWSCLIENTID, GWSCLIENTSECRET)
3. Config file (~/.config/gws/config.yaml)

logout — Remove stored credentials

gws auth logout

Revokes the token server-side with Google, then deletes the local token at ~/.config/gws/token.json.

Configuration

Environment Variables

export GWS_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GWS_CLIENT_SECRET="your-client-secret"

Config File (~/.config/gws/config.yaml)

client_id: "your-client-id.apps.googleusercontent.com"
client_secret: "your-client-secret"
services:
  - gmail
  - calendar
  - chat

Token Management

• Token stored at: ~/.config/gws/token.json (atomic writes, file-locked)
• Granted services tracked in: ~/.config/gws/granted_services.json
• Tokens auto-refresh when expired; refresh tokens preserved across re-auth
• Scoped login: use --services to request only needed scopes (smaller consent screen)
• Default services can be set in config.yaml: services: [gmail, calendar, chat]
• To add more scopes, re-run gws auth login --services gmail,calendar,chat,drive
• Logout revokes the token server-side before deleting locally

Tips for AI Agents

• Always check gws auth status before running any gws command to verify authentication
• If auth fails, guide users to the setup guide at references/setup-guide.md
• Credentials should NEVER be committed to version control or output in logs
• The OAuth flow opens a browser — this requires a desktop environment or manual URL handling
• Token refresh is automatic; if a command fails with auth errors, try gws auth logout then gws auth login