Index of every page on this site: llms.txt
All skills
googleworkspace avatar

/gws-gmail-watch

@cd3697e
by Google Workspacegoogleworkspace/cli32k stars
1,997
Run it yourself

Gmail: Watch for new emails and stream them as NDJSON.

Use this Skill: https://skilld.dev/gh/googleworkspace/cli/gws-gmail-watch

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈18 tokens for metadata: the name and description. ≈424 when used: this file.

How this Skill uses context

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈72 characters, or 0.9%.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

gmail +watch

PREREQUISITE: Read ../gws-shared/SKILL.md for auth, global flags, and security rules. If missing, run gws generate-skills to create it.

Watch for new emails and stream them as NDJSON

Usage

gws gmail +watch

Flags

Flag Required Default Description
--project — — GCP project ID for Pub/Sub resources
--subscription — — Existing Pub/Sub subscription name (skip setup)
--topic — — Existing Pub/Sub topic with Gmail push permission already granted
--label-ids — — Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD)
--max-messages — 10 Max messages per pull batch
--poll-interval — 5 Seconds between pulls
--msg-format — full Gmail message format: full, metadata, minimal, raw
--once — — Pull once and exit
--cleanup — — Delete created Pub/Sub resources on exit
--output-dir — — Write each message to a separate JSON file in this directory

Examples

gws gmail +watch --project my-gcp-project
gws gmail +watch --project my-project --label-ids INBOX --once
gws gmail +watch --subscription projects/p/subscriptions/my-sub
gws gmail +watch --project my-project --cleanup --output-dir ./emails

Tips

  • Gmail watch expires after 7 days — re-run to renew.
  • Without --cleanup, Pub/Sub resources persist for reconnection.
  • Press Ctrl-C to stop gracefully.

See Also

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2mo5 checks · Risk SAFE
  • Gen Agent Trust Hub2mo

    This skill allows an agent to monitor and stream Gmail messages using the gws CLI. The primary security risk is that the agent will process untrusted content from incoming emails, which could contain malicious instructions designed to manipulate the agent's behavior.

  • Socket2mo

    No alerts

  • Snyk2mo

    Risk: MEDIUM · 1 issue

  • Runlayer8mo

    1/1 file flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at cd3697e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 8 months ago
Other metadata
metadata
{
  "version": "0.22.5",
  "openclaw": {
    "category": "productivity",
    "requires": {
      "bins": [
        "gws"
      ]
    },
    "cliHelp": "gws gmail +watch --help"
  }
}
  • CLI
  • gmail
  • google-workspace
  • pub-sub
  • email
  • streaming
  • ndjson
  • gcp
  • watch

README badge

README badge for googleworkspace/cli/gws-gmail-watch

Watches Gmail for new emails and streams them as NDJSON via Google Cloud Pub/Sub, with options to filter by label, batch size, and output format. Use this to build email intake pipelines or monitor specific Gmail labels in real time without polling the Gmail API directly.

Generated from the current SKILL.md.

Does this work with Gmail accounts that have 2FA enabled?
Authentication is handled by the shared gws-shared skill, which manages Google Workspace OAuth. 2FA is handled by Google's auth flow—no special setup needed.
How long does the watch stay active?
Gmail watch expires after 7 days. You must re-run the command to renew the subscription.
What happens to Pub/Sub resources if I stop the command?
By default, Pub/Sub topic and subscription persist after exit, allowing you to reconnect without recreating them. Use --cleanup to delete them on exit.
Can I filter emails by labels?
Yes. Use the --label-ids flag with comma-separated Gmail label IDs like INBOX or UNREAD to watch only messages in those labels.

Generated from the current SKILL.md. These answers refresh after source changes.