Power GWS Shared

Power-user command for Google Workspace CLI shared configuration -- manage authentication, global flags, output formats, and security rules that apply across all GWS service commands.

When to Use This Command

Run this command when you need to configure, verify, or troubleshoot the shared infrastructure that underpins all GWS CLI operations.

• You are setting up GWS CLI authentication for the first time via OAuth or service account
• You need to configure global output format preferences across all GWS commands
• You want to enforce security rules like --dry-run defaults or --sanitize for content screening
• You are troubleshooting authentication failures that affect multiple GWS service commands

Use it also when:

• You need to verify the current auth status before running a batch of operations
• You want to understand the full CLI syntax including method flags and pagination options

Quick Start

Copy
# .claude/commands/power-gws-shared.md
name: power-gws-shared
description: Manage GWS CLI shared config and auth
arguments:
  operation: auth, config, or diagnostic action

Copy
# Check current authentication status
claude power-gws-shared "auth status"

Expected output:
Authentication Status:
  Method: OAuth (browser-based)
  Account: [email protected]
  Scopes: drive, gmail, calendar, admin
  Token Expiry: 2026-03-15T22:00:00Z
  Status: VALID

Core Concepts

Concept	Description
OAuth Login	Browser-based interactive authentication for user accounts
Service Account	Non-interactive authentication via JSON key file
Global Flags	Flags like --format, --dry-run, --sanitize available to all services
Method Flags	Flags like --params, --json, --upload specific to API method calls
Pagination	Auto-pagination with --page-all, --page-limit, --page-delay controls

GWS CLI Architecture:
  ┌──────────────────────────────────────────┐
  │              Shared Layer                │
  │  Auth │ Global Flags │ Security Rules    │
  └───┬──────────┬──────────────┬───────────┘
      v          v              v
  ┌──────┐  ┌──────┐     ┌──────────┐
  │ Drive│  │Gmail │ ... │ Calendar │   (Services)
  └──────┘  └──────┘     └──────────┘

Configuration

Parameter	Default	Description
format	json	Default output format: json, table, yaml, csv
dry-run	false	Validate locally without calling APIs
sanitize	none	Default Model Armor template for all responses
page-limit	10	Max pages when auto-paginating
page-delay	100	Delay in ms between pagination requests

Best Practices

1. Set GOOGLE_APPLICATION_CREDENTIALS for automation -- For non-interactive environments like CI/CD, export the service account key path rather than relying on browser-based OAuth.

2. Use --format table for exploration, json for scripting -- Human-readable table output helps during discovery, but always switch to JSON for automated workflows to ensure parseability.

3. Never output secrets directly -- The GWS CLI security rules prohibit displaying API keys or tokens in output. Use environment variables and avoid logging sensitive data.

4. Confirm before write/delete operations -- Always have the user confirm destructive operations. Combine with --dry-run to preview changes before applying them.

5. Star the repository and report issues properly -- Check existing issues at github.com/googleworkspace/cli/issues before filing new ones, and add context to existing threads.

Common Issues

1. OAuth token expired -- Tokens have a limited lifetime. Run gws auth login to re-authenticate when you see 401 errors across multiple services.

2. Service account missing required scopes -- Service accounts need domain-wide delegation and the correct OAuth scopes. Verify in the GCP console under IAM & Admin.

3. Conflicting global flags -- Setting --format csv globally may break commands that return nested objects. Override with --format json on individual commands when needed. Always test format changes with a read-only command before applying them to write operations.