gws-auth

name	gws-auth
description	Authenticate and manage credentials for the gws CLI — login, logout, status, scopes, service accounts, and credential storage.

gws auth

Note: See the gws-shared skill for global flags and security rules.

Manage authentication and credentials for the gws CLI.

Auth Subcommands

gws auth login       # Interactive OAuth2 login (opens browser)
gws auth logout      # Remove stored credentials
gws auth setup       # Guided first-run setup wizard
gws auth status      # Show current auth state and active scopes
gws auth export      # Export credentials for use in other tools

Login Options

Minimal scopes (default — safest for unverified apps)

gws auth login

Default scopes: Drive, Sheets, Gmail, Calendar, Docs, Slides, Tasks.

Full scopes (includes Pub/Sub and Cloud Platform)

gws auth login --full

Adds pubsub and cloud-platform scopes. Requires a verified OAuth app or Workspace domain admin approval.

Custom scopes

gws auth login --scopes drive,gmail,sheets,pubsub

Unrecognized service names are resolved dynamically from Discovery docs.

Read-only access

gws auth login --readonly

Grants only .readonly scopes for all services.

Credential Sources (Priority Order)

1. GOOGLE_WORKSPACE_CLI_TOKEN — Pre-obtained OAuth2 access token (highest priority)
2. GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE — Path to OAuth credentials JSON
3. Encrypted credentials — AES-256-GCM encrypted at ~/.config/gws/
4. GOOGLE_APPLICATION_CREDENTIALS — Standard Google ADC (fallback)

Service Account Support

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json
gws drive files list

Credential Storage

• Credentials are stored at ~/.config/gws/ (override with GOOGLE_WORKSPACE_CLI_CONFIG_DIR)
• Encrypted with AES-256-GCM
• Encryption key stored in OS keyring by default
• For headless/Docker/CI: export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

Environment Variables

Variable	Description
GOOGLE_WORKSPACE_CLI_TOKEN	Pre-obtained OAuth2 access token
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE	Path to OAuth credentials JSON
GOOGLE_WORKSPACE_CLI_CLIENT_ID	OAuth client ID
GOOGLE_WORKSPACE_CLI_CLIENT_SECRET	OAuth client secret
GOOGLE_WORKSPACE_CLI_CONFIG_DIR	Override config directory
GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND	keyring (default) or file
GOOGLE_APPLICATION_CREDENTIALS	Standard Google ADC path

Common Workflows

First-time setup

gws auth setup          # Guided wizard
gws auth status         # Verify it worked
gws gmail +triage       # Test with a read operation

Check current status

gws auth status

Re-authenticate with broader scopes

gws auth login --scopes drive,gmail,sheets,calendar,pubsub,cloud-platform

Tips

• Start with gws auth login (minimal scopes) — add more later with --scopes
• Use gws auth status to verify permissions before running commands
• For CI/CD, set GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file and provide credentials via env vars
• Never share or log the output of gws auth export