gws-gmail-watch

1# gmail +watch
2 
3> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
4 
5Watch for new emails and stream them as NDJSON
6 
7## Usage
8 
9```bash
10gws gmail +watch
11```
12 
13## Flags
14 
15| Flag | Required | Default | Description |
16|------|----------|---------|-------------|
17| `--project` | — | — | GCP project ID for Pub/Sub resources |
18| `--subscription` | — | — | Existing Pub/Sub subscription name (skip setup) |
19| `--topic` | — | — | Existing Pub/Sub topic with Gmail push permission already granted |
20| `--label-ids` | — | — | Comma-separated Gmail label IDs to filter (e.g., INBOX,UNREAD) |
21| `--max-messages` | — | 10 | Max messages per pull batch |
22| `--poll-interval` | — | 5 | Seconds between pulls |
23| `--msg-format` | — | full | Gmail message format: full, metadata, minimal, raw |
24| `--once` | — | — | Pull once and exit |
25| `--cleanup` | — | — | Delete created Pub/Sub resources on exit |
26| `--output-dir` | — | — | Write each message to a separate JSON file in this directory |
27 
28## Examples
29 
30```bash
31gws gmail +watch --project my-gcp-project
32gws gmail +watch --project my-project --label-ids INBOX --once
33gws gmail +watch --subscription projects/p/subscriptions/my-sub
34gws gmail +watch --project my-project --cleanup --output-dir ./emails
35```
36 
37## Tips
38 
39- Gmail watch expires after 7 days — re-run to renew.
40- Without --cleanup, Pub/Sub resources persist for reconnection.
41- Press Ctrl-C to stop gracefully.
42…