File contents gmail +watch
PREREQUISITE: Read ../gws-shared/SKILL.md for auth, global flags, and security rules. If missing, stop and repair the declarative skill deployment.
Watch for new emails and stream them as NDJSON
This helper can create Pub/Sub resources and change Gmail push settings. Get explicit approval before setup, API enablement, or cleanup.
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
1 --- 2 name: gws-gmail-watch 3 description: gmail +watch 4 --- 5 # gmail +watch 6 7 > **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, stop and repair the declarative skill deployment. 8 9 Watch for new emails and stream them as NDJSON 10 11 This helper can create Pub/Sub resources and change Gmail push settings. Get explicit approval before setup, API enablement, or cleanup. 12 13 ## Usage 14 15 ```bash 16 gws gmail +watch 17 ``` 18 19 ## Flags 20 21 | Flag | Required | Default | Description | 22 |------|----------|---------|-------------| 23 | `--project` | — | — | GCP project ID for Pub/Sub resources | 24 | `--subscription` | — | — | Existing Pub/Sub subscription name (skip setup) | 25 | `--topic` | — | — | Existing Pub/Sub topic with Gmail push permission already granted | 26 | `--label-ids` | — | — | Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD) | 27 | `--max-messages` | — | 10 | Max messages per pull batch | 28 | `--poll-interval` | — | 5 | Seconds between pulls | 29 | `--msg-format` | — | full | Gmail message format: full, metadata, minimal, raw | 30 | `--once` | — | — | Pull once and exit | 31 | `--cleanup` | — | — | Delete created Pub/Sub resources on exit | 32 | `--output-dir` | — | — | Write each message to a separate JSON file in this directory | 33 34 ## Examples 35 36 ```bash 37 gws gmail +watch --project my-gcp-project 38 gws gmail +watch --project my-project --label-ids INBOX --once 39 gws gmail +watch --subscription projects/p/subscriptions/my-sub 40 gws gmail +watch --project my-project --cleanup --output-dir ./emails 41 ``` 42 43 ## Tips 44 45 - Gmail watch expires after 7 days — re-run to renew. 46 - Without --cleanup, Pub/Sub resources persist for reconnection. 47 - Press Ctrl-C to stop gracefully. 48 49 ## See Also 50 51 - [gws-shared](../gws-shared/SKILL.md) — Global flags and auth 52 - [gws-gmail](../gws-gmail/SKILL.md) — All send, read, and manage email commands
commit 7c212b5563
Frequently asked questions How do I install the Gws Gmail Watch skill? Run npx skillmds@latest add wimpysworld/gws-gmail-watch in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
What does the Gws Gmail Watch skill do? gmail +watch It is listed under Coding & Dev Tools on SkillMD.
Is Gws Gmail Watch safe to use? This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
Which AI agents work with Gws Gmail Watch? This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Is Gws Gmail Watch free to use? Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Who published Gws Gmail Watch? wimpysworld (@wimpysworld) published this skill. Their other Agent Skills are listed on their SkillMD profile.
wimpysworld