Smart Google Workspace Tool

Intelligent dispatcher for Google Workspace CLI operations that auto-detects the target service, validates authentication, and executes GWS commands with schema-aware parameter building.

When to Use This Command

Run this command when you need to execute any Google Workspace API operation without remembering the exact service name or method syntax.

• You want a single entry point to interact with Gmail, Drive, Calendar, Admin, or any other GWS service
• You need to discover available resources and methods across Google Workspace APIs
• You want automatic authentication checks before executing operations
• You are building automation scripts that span multiple GWS services

Use it also when:

• You need help constructing --params and --json flags from schema output
• You want dry-run validation before executing write or delete operations

Quick Start

Copy
# .claude/commands/smart-gws-tool.md
name: smart-gws-tool
description: Auto-detect and execute Google Workspace CLI operations
arguments:
  operation: The GWS service, resource, and method to run

Copy
# Invoke the command
claude smart-gws-tool "calendar events list --params '{\"calendarId\": \"primary\"}'"

Expected output:
[
  {
    "id": "evt_abc123",
    "summary": "Team Standup",
    "start": { "dateTime": "2026-03-15T09:00:00Z" },
    "end": { "dateTime": "2026-03-15T09:30:00Z" }
  }
]

Core Concepts

Concept	Description
Service	A GWS API product (e.g., calendar, drive, gmail, admin)
Resource	An entity within a service (e.g., events, files, messages)
Method	The action to perform (e.g., list, get, insert, delete)
Schema	Parameter definitions retrieved via gws schema before execution
Global Flags	Shared flags like --format, --dry-run, --sanitize

Request Flow:
  User Input ──> Service Detection ──> Auth Check ──> Schema Lookup
       │                                                    │
       │                                                    v
       └──── Result <── Format Output <── Execute API <── Build Flags

Configuration

Parameter	Default	Description
format	json	Output format: json, table, yaml, csv
dry-run	false	Validate without calling the API
page-all	false	Auto-paginate through all results
page-limit	10	Maximum pages when using --page-all
sanitize	none	Model Armor template for content screening

Best Practices

1. Always verify authentication first -- Run gws auth status before executing operations to avoid cryptic error messages from unauthenticated requests.

2. Inspect schemas before write operations -- Use gws schema <service>.<resource>.<method> to understand required parameters, types, and constraints before constructing your command.

3. Use dry-run for destructive actions -- Pass --dry-run when executing delete, update, or patch methods to validate your command without making actual changes.

4. Prefer table format for interactive use -- When exploring data interactively, --format table provides human-readable output, while json is better for scripting and piping.

5. Leverage auto-pagination carefully -- The --page-all flag fetches every page, which can generate large output; combine with --page-limit to cap results.

Common Issues

1. Authentication expired or missing -- Run gws auth login for browser-based OAuth or set GOOGLE_APPLICATION_CREDENTIALS for service accounts. Verify with gws auth status.

2. Unknown service or method -- The service name must match the GWS CLI registry. Run gws --help to list all available services, then gws <service> --help for resources and methods.

3. Malformed --params or --json flags -- Both flags require valid JSON strings wrapped in single quotes. Escape inner quotes properly: --params '{"key": "value"}'. When building complex JSON, consider writing the JSON to a temporary file and using --json "$(cat params.json)" to avoid nested escaping issues in your shell.

Additional Notes

The Smart GWS Tool supports all Google Workspace APIs registered in the CLI, including Calendar, Drive, Gmail, Admin Directory, Groups Settings, Sheets, Slides, Tasks, Vault, Reseller, Chat, and ModelArmor. Each service follows the same gws <service> <resource> <method> [flags] syntax, making it straightforward to switch between services once you learn the pattern. The tool automatically validates that the specified service exists before attempting authentication, providing early failure for typos.

For batch operations across multiple services, consider writing a shell script that chains multiple gws calls. The authentication token is shared across all services within a session, so you only need to verify auth once at the start of your script. Use --format json consistently in scripts so you can pipe output through jq for filtering and transformation.