/gws

name: gws
description: Use the gws CLI for Google Calendar, Gmail, Drive, Sheets, Docs, Tasks, and cross-service Workspace workflows.
user-invocable: true
requires:
  bins:
    - gws
metadata:
  hybridclaw:
    category: productivity
    short_description: "Google Workspace via gws CLI."
    tags:
      - google
      - workspace
      - calendar
      - gmail
      - drive
      - sheets
      - docs
      - tasks
    related_skills:
      - google-workspace
    install:
      - id: gws
        kind: npm
        package: "@googleworkspace/cli"
        bins: ["gws"]
        label: Install Google Workspace CLI (npm)

Google Workspace via gws CLI

Step 1: Check auth before anything else

HybridClaw injects `GOOGLE_WORKSPACE_CLI_TOKEN` into the agent runtime when Google auth is configured with `hybridclaw auth login google`.

Run exactly `gws auth status` (no API call, instant) and parse the JSON output. Do not add `--json`; `gws auth status --json` is invalid because auth status already prints JSON by default.

Treat auth as configured when any of these are true:

• `credential_source` is `"token_env_var"`
• `token_env_var` is `true`
• `auth_method` is not `"none"`
• `storage` is not `"none"`

This matters because HybridClaw passes its Google OAuth token through `GOOGLE_WORKSPACE_CLI_TOKEN`; current `gws auth status` may still report `auth_method: "none"` for that env-token mode.

Only if none of the authenticated states above are present, tell the user:

> Run `hybridclaw auth login google` in your terminal to connect your Google account.

If env-token auth is present, do not ask the user to log in again. Continue with the requested `gws` command immediately.

That's it. Don't explain OAuth, GCP projects, scopes, or alternatives unless a later `gws` command returns an auth or scope error. The HybridClaw login flow works for both personal Gmail and Workspace accounts.

Step 2: Act immediately

Do not ask clarifying questions. Run the command with sensible defaults:

• Calendar → `primary` calendar, user's timezone
• Gmail → `userId: me`, unread inbox
• Drive → search by name keywords the user mentioned
• Sheets → search Drive first if user gave a name, not an ID

Only ask for clarification when there are genuinely ambiguous results (e.g., multiple spreadsheets matching a search).

Step 3: Pick the right commands

**Calendar**: See [references/calendar.md](references/calendar.md) **Gmail**: See [references/gmail.md](references/gmail.md) **Drive & Sheets & Docs**: See [references/drive-docs-sheets.md](references/drive-docs-sheets.md) **Cross-service workflows**: See [references/workflows.md](references/workflows.md)

For any service not covered above, use `gws <service> --help` to discover available resources and methods. The raw syntax is:

gws <service> <resource> <method> --params '{"key": "val"}' --json '{"body": "data"}'

Confirmation rules

Confirm before actions that **affect other people**:

• Sending email
• Inviting attendees to events
• Sharing files or folders

Do **not** confirm for actions that only affect the user:

• Blocking time on their own calendar
• Creating personal reminders or tasks
• Creating a private document or spreadsheet

The reason: asking "are you sure you want to block 2-4pm?" when the user just told you to block 2-4pm is friction, not safety.

Presenting results

Format JSON output into readable summaries. Group calendar events by day. Show email as sender + subject + snippet. Render sheets data as Markdown tables. Never dump raw JSON unless the user asks for it.