# Gws Gmail Watch

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

- Repository: https://github.com/googleworkspace/cli (32044 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add googleworkspace/cli --skill gws-gmail-watch -g -a claude-code -y`
Codex: `npx skills add googleworkspace/cli --skill gws-gmail-watch -g -a codex -y`
Cursor: `npx skills add googleworkspace/cli --skill gws-gmail-watch -g -a cursor -y`
Gemini CLI: `npx skills add googleworkspace/cli --skill gws-gmail-watch -g -a gemini-cli -y`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

```bash
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

```bash
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

- [gws-shared](../gws-shared/SKILL.md), Global flags and auth
- [gws-gmail](../gws-gmail/SKILL.md), All send, read, and manage email commands