Gws Meta Workflows

GWS Meta-Workflows

Six composable meta-workflows that chain Google Workspace CLI (gws) commands into end-to-end automations. Each workflow combines multiple GWS services (Gmail, Calendar, Drive, Docs, Model Armor) into a single orchestrated sequence.

Setup Guide

Walk the user through each step below. Do not skip ahead - confirm each step succeeds before moving to the next.

Step 1: Install the GWS CLI

The CLI is a Rust binary distributed via npm. It requires Node.js 18+.

npm install -g @googleworkspace/cli

Verify it installed:

gws --version

Expected output: gws 0.7.x (or newer). If the command is not found, ensure npm's global bin directory is in your PATH.

Alternative install methods:

# Via Cargo (requires Rust toolchain)
cargo install --git https://github.com/googleworkspace/cli --locked

# Via Nix
nix run github:googleworkspace/cli

Step 2: Install gcloud CLI (Required for Auth Setup)

The gws auth setup command uses gcloud to create a Google Cloud project and OAuth client automatically. Install it if not present:

# macOS
brew install --cask google-cloud-sdk

# Linux
curl https://sdk.cloud.google.com | bash

# Windows
# Download from https://cloud.google.com/sdk/docs/install

Verify:

gcloud --version

Step 3: Authenticate

This is a two-step process. First, set up a GCP project with OAuth credentials. Then authenticate your user account.

gws auth setup

This will:

• Create a new Google Cloud project (or use an existing one with --project PROJECT_ID)
• Enable all required Workspace APIs (Gmail, Calendar, Drive, Docs, Sheets, etc.)
• Create an OAuth 2.0 Desktop client
• Save the client secret to ~/.config/gws/client_secret.json

Then authenticate:

gws auth login -s drive,gmail,calendar,docs,sheets

The -s flag limits scope selection to specific services. This opens a browser for Google OAuth consent.

Important: "Google hasn't verified this app" warning. This is normal for self-created OAuth apps. Click Advanced then "Go to [app name] (unsafe)" to proceed. This is your own app running on your own GCP project - it is safe.

Verify authentication:

gws auth status

Should show "token_valid": true and your scopes listed.

Alternative auth methods (no gcloud needed):

If you cannot install gcloud, set up OAuth manually:

1. Go to Google Cloud Console
2. Create a project and enable Gmail, Calendar, Drive, Docs, Sheets APIs
3. Go to Credentials > Create Credentials > OAuth 2.0 Client ID > Desktop App
4. Download the JSON and save to ~/.config/gws/client_secret.json
5. Run gws auth login -s drive,gmail,calendar,docs,sheets

Or use an existing access token:

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)

Or a service account:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/service-account.json

Step 4: Install GWS Agent Skills (Optional but Recommended)

The GWS CLI binary and the GWS agent skills are separate. The CLI ships via npm. The agent skills (SKILL.md files that teach AI agents how to use the CLI) live in the GitHub repo and must be installed separately.

For Claude Code users:

# Clone the full skills collection
git clone https://github.com/googleworkspace/cli /tmp/gws-cli-repo
cp -r /tmp/gws-cli-repo/skills/gws-* ~/.claude/skills/
rm -rf /tmp/gws-cli-repo

Or install specific skills only:

git clone --depth 1 https://github.com/googleworkspace/cli /tmp/gws-cli-repo
cp -r /tmp/gws-cli-repo/skills/gws-gmail ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-drive ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-calendar ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-docs ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-sheets ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-workflow ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-modelarmor ~/.claude/skills/
cp -r /tmp/gws-cli-repo/skills/gws-shared ~/.claude/skills/
rm -rf /tmp/gws-cli-repo

For OpenClaw users:

git clone https://github.com/googleworkspace/cli /tmp/gws-cli-repo
ln -s /tmp/gws-cli-repo/skills/gws-* ~/.openclaw/skills/

Via npx (if supported by your agent framework):

npx skills add https://github.com/googleworkspace/cli

These skill files are not required for the meta-workflows below to work - they just give your agent additional context about each GWS service's capabilities.

Step 5: Verify Everything Works

Run these commands to confirm your setup:

# Should return your inbox summary
gws gmail +triage --max 3 --format json

# Should return today's calendar events
gws calendar +agenda --today --format json

# Should return recent Drive files
gws drive files list --params '{"pageSize":3,"fields":"files(id,name)"}'

If any command returns a 401 auth error, re-run gws auth login. If it returns a 403 scope error, re-run with broader scopes: gws auth login -s drive,gmail,calendar,docs,sheets.

MCP Server Setup (Optional)

To expose GWS as structured tools for any MCP-compatible client (Claude Desktop, VS Code, Cursor, etc.):

{
  "mcpServers": {
    "gws": {
      "command": "gws",
      "args": ["mcp", "-s", "drive,gmail,calendar", "-w", "-e"]
    }
  }
}

Flags: -s selects services (comma-separated, or all), -w includes workflow tools, -e includes helper tools.

Add this to your MCP config file:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code: ~/.claude/settings.json under mcpServers
• VS Code: .vscode/settings.json under mcp.servers

Safety Defaults

All workflows follow these principles:

• Drafts only - Never send emails automatically; always create drafts for human review
• Dry-run first - Use --dry-run on mutating operations before executing
• Field masks - Use --params '{"fields": "..."}' to limit response size and protect context windows
• Sanitize untrusted input - Use --sanitize <TEMPLATE> when processing external email content

Workflow 1: inbox-triage-and-auto-reply

What it does: Pulls unread emails, classifies them by type (action required / FYI / sales pitch / automated notification), drafts replies for routine messages, and creates calendar blocks for emails requiring deep work.

Step-by-step

1. Pull unread inbox summary

gws gmail +triage --max 50 --format json

Returns JSON array with sender, subject, date, and snippet for each unread message.

2. Get full message content for classification For each message that needs deeper inspection:

gws gmail users messages get \
  --params '{"userId":"me","id":"MESSAGE_ID","format":"full","fields":"id,snippet,payload.headers,labelIds"}'

3. Classify each message Use the agent's reasoning to categorize into:

• action_required - Needs a response or task creation
• fyi - Informational, no response needed
• sales_pitch - Vendor outreach, can be archived
• automated - Newsletters, receipts, notifications

4. Draft replies for routine messages

gws gmail users drafts create \
  --json '{"message":{"raw":"BASE64_ENCODED_RFC2822_MESSAGE"}}' \
  --params '{"userId":"me"}'

5. Create calendar blocks for action items For emails requiring focused work:

gws calendar +insert \
  --summary "Follow up: EMAIL_SUBJECT" \
  --start "2026-03-07T10:00:00-07:00" \
  --end "2026-03-07T10:30:00-07:00" \
  --description "Action item from email by SENDER_NAME. Message ID: MESSAGE_ID"

6. Convert action emails to tasks

gws workflow +email-to-task --message-id MESSAGE_ID

7. Present summary to user for approval Show: total emails processed, drafts created (with previews), calendar blocks created, tasks created. User approves or modifies before any draft is sent.

GWS Skills Referenced

Read these installed skills for detailed API reference before executing:

• @see ~/.claude/skills/gws-gmail-triage/SKILL.md - Inbox summary flags: --max, --query, --labels, --format
• @see ~/.claude/skills/gws-gmail/SKILL.md - Raw Gmail API: users.messages.get, users.drafts.create, users.labels.create
• @see ~/.claude/skills/gws-calendar-insert/SKILL.md - Event creation flags: --summary, --start, --end, --attendee, --description
• @see ~/.claude/skills/gws-workflow-email-to-task/SKILL.md - Email-to-task conversion: --message-id, --tasklist
• @see ~/.claude/skills/gws-shared/SKILL.md - Auth patterns, global flags (--dry-run, --sanitize, --format)

Workflow 2: pre-meeting-context-compiler

What it does: Before any calendar event, pulls the attendee list, searches Gmail for recent threads with each attendee, finds relevant Drive docs, and compiles everything into a Google Docs briefing.

Step-by-step

1. Get the next meeting details

gws workflow +meeting-prep --format json

Returns next event with attendees, description, and linked documents.

For a specific calendar:

gws workflow +meeting-prep --calendar "Work" --format json

2. List upcoming events to pick a specific meeting

gws calendar +agenda --today --format json

3. Get full event details including attendees

gws calendar events get \
  --params '{"calendarId":"primary","eventId":"EVENT_ID","fields":"summary,description,attendees,start,end,hangoutLink,attachments"}'

4. Search Gmail for recent threads with each attendee For each attendee email:

gws gmail +triage --max 10 --query "from:ATTENDEE_EMAIL OR to:ATTENDEE_EMAIL newer_than:14d" --format json

5. Search Drive for relevant documents

gws drive files list \
  --params '{"q":"fullText contains '''MEETING_TOPIC''' and modifiedTime > '''2026-02-20T00:00:00Z'''","fields":"files(id,name,webViewLink,modifiedTime)","pageSize":10}'

6. Create a briefing document

gws docs documents create \
  --json '{"title":"Meeting Brief: EVENT_SUMMARY - DATE"}'

7. Populate the briefing

gws docs +write --document DOC_ID --text "COMPILED_BRIEFING_CONTENT"

The briefing should include:

• Meeting title, time, and video link
• Attendee list with recent interaction context
• Key email threads summarized
• Relevant Drive documents linked
• Suggested talking points based on context

GWS Skills Referenced

Read these installed skills for detailed API reference before executing:

• @see ~/.claude/skills/gws-workflow-meeting-prep/SKILL.md - Meeting prep flags: --calendar, --format
• @see ~/.claude/skills/gws-calendar-agenda/SKILL.md - Agenda flags: --today, --week, --days, --calendar
• @see ~/.claude/skills/gws-calendar/SKILL.md - Raw Calendar API: events.get, events.list, freebusy.query
• @see ~/.claude/skills/gws-gmail-triage/SKILL.md - Email search with --query for per-attendee thread lookup
• @see ~/.claude/skills/gws-drive/SKILL.md - Raw Drive API: files.list with q parameter for document search
• @see ~/.claude/skills/gws-docs/SKILL.md - Raw Docs API: documents.create, documents.get
• @see ~/.claude/skills/gws-docs-write/SKILL.md - Append text: --document, --text
• @see ~/.claude/skills/gws-shared/SKILL.md - Auth patterns, global flags

Workflow 3: client-onboarding-automation

What it does: From a single command with a client name, creates a Drive folder structure from templates, populates contract docs, schedules a kickoff meeting, and drafts a welcome email.

Step-by-step

1. Create the client folder in Drive

gws drive files create \
  --json '{"name":"CLIENT_NAME","mimeType":"application/vnd.google-apps.folder","parents":["CLIENTS_FOLDER_ID"]}'

2. Create subfolders For each subfolder (Contracts, Deliverables, Communications, Assets):

gws drive files create \
  --json '{"name":"SUBFOLDER_NAME","mimeType":"application/vnd.google-apps.folder","parents":["CLIENT_FOLDER_ID"]}'

3. Copy template documents into the client folder

gws drive files copy \
  --params '{"fileId":"TEMPLATE_DOC_ID"}' \
  --json '{"name":"CLIENT_NAME - Contract","parents":["CONTRACTS_FOLDER_ID"]}'

4. Create a tracking spreadsheet

gws sheets spreadsheets create \
  --json '{"properties":{"title":"CLIENT_NAME - Project Tracker"}}'

5. Populate the tracker with initial data

gws sheets spreadsheets values append \
  --params '{"spreadsheetId":"SHEET_ID","range":"A1","valueInputOption":"USER_ENTERED"}' \
  --json '{"values":[["Task","Status","Owner","Due Date"],["Kickoff Meeting","Scheduled","",""],["Contract Review","Pending","",""],["Onboarding Checklist","Not Started","",""]]}'

6. Move the tracker to the client folder

gws drive files update \
  --params '{"fileId":"SHEET_ID","addParents":"CLIENT_FOLDER_ID","removeParents":"ROOT_FOLDER_ID"}'

7. Schedule the kickoff meeting

gws calendar +insert \
  --summary "Kickoff: CLIENT_NAME" \
  --start "PROPOSED_START_ISO8601" \
  --end "PROPOSED_END_ISO8601" \
  --attendee "client@example.com" \
  --description "Welcome! Folder: DRIVE_FOLDER_LINK\nAgenda:\n1. Introductions\n2. Scope review\n3. Timeline alignment\n4. Next steps" \
  --dry-run

Remove --dry-run after user confirms the time.

8. Draft the welcome email

gws gmail users drafts create \
  --json '{"message":{"raw":"BASE64_RFC2822_WELCOME_EMAIL"}}' \
  --params '{"userId":"me"}'

The welcome email should include:

• Link to the shared Drive folder
• Kickoff meeting date/time
• What to expect in the first week
• Key contacts

GWS Skills Referenced

Read these installed skills for detailed API reference before executing:

• @see ~/.claude/skills/gws-drive/SKILL.md - Raw Drive API: files.create (folders), files.copy (templates), files.update (move between folders)
• @see ~/.claude/skills/gws-drive-upload/SKILL.md - File upload helper with automatic metadata
• @see ~/.claude/skills/gws-sheets/SKILL.md - Raw Sheets API: spreadsheets.create
• @see ~/.claude/skills/gws-sheets-append/SKILL.md - Append rows helper for populating tracker data
• @see ~/.claude/skills/gws-calendar-insert/SKILL.md - Event creation: --summary, --start, --end, --attendee, --description
• @see ~/.claude/skills/gws-gmail/SKILL.md - Raw Gmail API: users.drafts.create for welcome email
• @see ~/.claude/skills/gws-shared/SKILL.md - Auth patterns, global flags

Workflow 4: weekly-activity-digest-generator

What it does: Every Friday (or on demand), pulls sent emails, calendar events, and recently modified Drive docs from the past 7 days. Compiles into a structured summary document.

Step-by-step

1. Get the quick weekly digest

gws workflow +weekly-digest --format json

Returns meeting count and unread email summary for the week.

2. Pull this week's calendar events

gws calendar +agenda --week --format json

3. Pull sent emails from the past 7 days

gws gmail +triage --max 100 --query "in:sent newer_than:7d" --format json

4. Find recently modified Drive documents

gws drive files list \
  --params '{"q":"modifiedTime > '''SEVEN_DAYS_AGO_ISO8601''' and mimeType != '''application/vnd.google-apps.folder'''","fields":"files(id,name,webViewLink,modifiedTime,mimeType)","pageSize":50,"orderBy":"modifiedTime desc"}'

5. Create the digest document

gws docs documents create \
  --json '{"title":"Weekly Digest: WEEK_START - WEEK_END"}'

6. Write the digest content

gws docs +write --document DOC_ID --text "COMPILED_DIGEST"

The digest structure:

• Meetings attended - Count, list with attendees
• Emails sent - Count, key threads summarized
• Documents touched - List with links
• Key outcomes - Agent-generated summary of the week's activity
• Suggested priorities for next week - Based on open threads and upcoming meetings

7. Optionally announce in Chat

gws workflow +file-announce --file-id DOC_ID --space "spaces/SPACE_ID"

GWS Skills Referenced

Read these installed skills for detailed API reference before executing:

• @see ~/.claude/skills/gws-workflow-weekly-digest/SKILL.md - Weekly digest flags: --format
• @see ~/.claude/skills/gws-calendar-agenda/SKILL.md - Agenda flags: --week, --format for weekly event listing
• @see ~/.claude/skills/gws-gmail-triage/SKILL.md - Email search with --query "in:sent newer_than:7d" for sent mail
• @see ~/.claude/skills/gws-drive/SKILL.md - Raw Drive API: files.list with modifiedTime filter and orderBy
• @see ~/.claude/skills/gws-docs/SKILL.md - Raw Docs API: documents.create for digest doc
• @see ~/.claude/skills/gws-docs-write/SKILL.md - Append digest content: --document, --text
• @see ~/.claude/skills/gws-workflow-file-announce/SKILL.md - Announce file in Chat space: --file-id, --space
• @see ~/.claude/skills/gws-shared/SKILL.md - Auth patterns, global flags

Workflow 5: email-prompt-injection-scanner

What it does: Scans inbound emails for prompt injection attempts - hidden instructions, invisible text, or adversarial payloads that could manipulate an AI agent processing the inbox. Uses Model Armor for detection and quarantines suspicious messages.

Step-by-step

1. Pull recent unread emails

gws gmail +triage --max 30 --format json

2. Get full message content for each email

gws gmail users messages get \
  --params '{"userId":"me","id":"MESSAGE_ID","format":"full"}'

3. Sanitize the email body through Model Armor

gws modelarmor +sanitize-prompt \
  --template "projects/PROJECT_ID/locations/LOCATION/templates/TEMPLATE_ID" \
  --text "EMAIL_BODY_CONTENT"

This checks for:

• Prompt injection patterns
• Hidden instructions in HTML/CSS
• Adversarial payloads designed to hijack agent behavior

4. Check the sanitization result Model Armor returns a verdict. If flagged:

5a. If clean - mark as safe for agent processing Continue with normal inbox triage workflow.

5b. If flagged - quarantine the message Apply a quarantine label:

gws gmail users messages modify \
  --params '{"userId":"me","id":"MESSAGE_ID"}' \
  --json '{"addLabelIds":["QUARANTINE_LABEL_ID"]}'

6. Create the quarantine label (one-time setup)

gws gmail users labels create \
  --params '{"userId":"me"}' \
  --json '{"name":"AI-Quarantine","labelListVisibility":"labelShow","messageListVisibility":"show","color":{"backgroundColor":"#cc3a21","textColor":"#ffffff"}}'

7. Generate a security report Summarize:

• Total emails scanned
• Clean vs flagged count
• Flagged email details (sender, subject, detection reason)
• Recommended actions

Setting Up Model Armor

Before first use, create a template:

gws modelarmor +create-template \
  --project PROJECT_ID \
  --location us-central1 \
  --name email-scanner

Or set a default via environment:

export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/PROJECT_ID/locations/us-central1/templates/email-scanner"
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="warn"

GWS Skills Referenced

Read these installed skills for detailed API reference before executing:

• @see ~/.claude/skills/gws-gmail-triage/SKILL.md - Inbox listing with --max, --format json
• @see ~/.claude/skills/gws-gmail/SKILL.md - Raw Gmail API: users.messages.get (full content), users.messages.modify (apply labels), users.labels.create (quarantine label)
• @see ~/.claude/skills/gws-modelarmor-sanitize-prompt/SKILL.md - Prompt sanitization: --template, --text
• @see ~/.claude/skills/gws-modelarmor-create-template/SKILL.md - Template creation: --project, --location, --name
• @see ~/.claude/skills/gws-modelarmor/SKILL.md - Model Armor overview and discovery commands
• @see ~/.claude/skills/gws-shared/SKILL.md - Auth patterns, global flags

Workflow 6: scheduling-conflict-resolver

What it does: When a scheduling email arrives, extracts proposed times, checks your calendar for conflicts and preferences, queries free/busy data, and drafts a reply with your available slots.

Step-by-step

1. Get the scheduling email content

gws gmail users messages get \
  --params '{"userId":"me","id":"MESSAGE_ID","format":"full","fields":"id,snippet,payload.headers,payload.body"}'

The agent parses the email body to extract proposed meeting times.

2. Check your calendar for the proposed time range

gws calendar +agenda --days 7 --format json

3. Query free/busy for specific time slots

gws calendar freebusy query \
  --json '{"timeMin":"START_ISO8601","timeMax":"END_ISO8601","items":[{"id":"primary"}]}'

4. Find open slots Compare proposed times against free/busy data. Identify:

• Which proposed times work
• Which conflict
• Alternative open slots nearby

5. Draft a reply with availability

gws gmail users drafts create \
  --json '{"message":{"raw":"BASE64_ENCODED_REPLY","threadId":"THREAD_ID"}}' \
  --params '{"userId":"me"}'

The reply should:

• Acknowledge the scheduling request
• Confirm available proposed times
• Suggest alternatives for conflicting times
• Include timezone context

6. Optionally create a tentative calendar hold

gws calendar +insert \
  --summary "HOLD: Meeting with SENDER_NAME" \
  --start "CHOSEN_TIME_ISO8601" \
  --end "CHOSEN_END_ISO8601" \
  --description "Tentative hold pending confirmation. Thread: MESSAGE_ID" \
  --dry-run

GWS Skills Referenced

Read these installed skills for detailed API reference before executing:

• @see ~/.claude/skills/gws-gmail/SKILL.md - Raw Gmail API: users.messages.get (read scheduling email), users.drafts.create (draft reply with threadId to keep in thread)
• @see ~/.claude/skills/gws-calendar-agenda/SKILL.md - Agenda flags: --days 7, --format json for schedule overview
• @see ~/.claude/skills/gws-calendar/SKILL.md - Raw Calendar API: freebusy.query (check availability), events.list, events.quickAdd
• @see ~/.claude/skills/gws-calendar-insert/SKILL.md - Create tentative holds: --summary, --start, --end, --dry-run
• @see ~/.claude/skills/gws-shared/SKILL.md - Auth patterns, global flags

Command Quick Reference

Helpers (High-Level)

Raw API (Low-Level)

Global Flags

Schema Discovery

gws <service> --help                    # List resources and methods
gws schema <service>.<resource>.<method> # Inspect parameters and types

Chaining Workflows Together

These workflows are composable. Examples:

Morning routine:

1. Run inbox-triage-and-auto-reply to clear overnight email
2. Run pre-meeting-context-compiler for today's first meeting
3. Run scheduling-conflict-resolver on any scheduling emails found in triage

End of week:

1. Run weekly-activity-digest-generator to compile the week
2. Run email-prompt-injection-scanner as a security audit

New client signed:

1. Run client-onboarding-automation with the client details
2. The kickoff meeting created feeds into pre-meeting-context-compiler when the day arrives

Troubleshooting

Auth errors: Run gws auth status to check. Re-authenticate with gws auth login.

Context window overflow: Always use --fields to limit response payloads. Large Gmail messages or Drive listings can overwhelm agent context.

Model Armor not available: Requires Google Cloud project with Model Armor API enabled and cloud-platform scope. Skip --sanitize if not configured.

Rate limits: Use --page-delay 200 when paginating large result sets. The Gmail API has per-user rate limits.

Shell escaping with ! in Sheets ranges: Avoid Sheet1!A1 in --params JSON - the ! causes shell history expansion and JSON parse errors. Use just "A1" instead (defaults to first sheet). If you must specify the sheet, use $'...' quoting or a heredoc.

Command not found: Run gws <service> --help to discover available resources and methods. The CLI builds commands dynamically from Google's Discovery Service.