Gws Gmail Watch
- 30.4k installs
- 30k repo stars
- Updated July 22, 2026
- googleworkspace/cli
gws is a CLI that exposes all Google Workspace APIs (Gmail, Drive, Calendar, Sheets, Chat) with structured JSON output and agent skills.
About
gws is a unified CLI for all Google Workspace APIs (Gmail, Drive, Calendar, Sheets, Chat) built for humans and AI agents. It dynamically reads Google's Discovery Service to auto-generate the command surface, so it stays current as Google adds new endpoints. Every response is structured JSON, making it natural to pair with agent skills included in the distribution.
- Dynamic API surface reads Google Discovery Service at runtime - auto-updates as Google adds endpoints
- 40+ included agent skills pair with LLMs to manage Gmail, Drive, Calendar, Sheets without custom tooling
- Structured JSON output and --dry-run preview for both humans and AI agents
Gws Gmail Watch by the numbers
- 30,354 all-time installs (skills.sh)
- +924 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #27 of 690 Office & Documents skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
gws-gmail-watch capabilities & compatibility
- Works with
- gmail · google drive
- Use cases
- orchestration
npx skills add https://github.com/googleworkspace/cli --skill gws-gmail-watchAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 30.4k |
|---|---|
| repo stars | ★ 30k |
| Security audit | 2 / 3 scanners passed |
| Last updated | July 22, 2026 |
| Repository | googleworkspace/cli ↗ |
How do you stream Gmail events as NDJSON?
CLI access to Google Workspace (Gmail, Drive, Calendar, Sheets) with structured JSON for agent automation.
Who is it for?
Developers automating Gmail triage with the gws CLI and GCP Pub/Sub who need machine-readable mailbox events.
Skip if: Developers who only need one-off message reads or lack gws auth and a configured GCP project should skip gws-gmail-watch.
When should I use this skill?
User asks to watch Gmail, stream new emails, or pipe mailbox events into an agent workflow with gws.
What you get
Continuous NDJSON stream of Gmail watch events, optional Pub/Sub subscription wiring
- NDJSON Gmail event stream
- Pub/Sub subscription linkage
By the numbers
- Skill metadata version 0.22.5
- Requires the gws CLI binary
Files
gmail +watch
PREREQUISITE: Read../gws-shared/SKILL.mdfor auth, global flags, and security rules. If missing, rungws generate-skillsto create it.
Watch for new emails and stream them as NDJSON
Usage
gws gmail +watchFlags
| 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 ./emailsTips
- 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 — Global flags and auth
- gws-gmail — All send, read, and manage email commands
Related skills
Lark DocGenerate, update, and maintain structured documentation directly inside Lark/Feishu using natural language and agentic workflows.475kLark DriveLet their coding agents read, create, update and search documents stored in Lark (Feishu) Drive directly from prompts.475kLark SheetsConnect Claude, Cursor or other agents directly to Feishu/Lark spreadsheets for live data reads, writes, and structured automation.474kLark WikiGenerate, update, and sync structured knowledge bases inside Lark (Feishu) directly from code, specs, or agent output.474kLark WhiteboardGenerate, edit, and collaborate on visual diagrams and flowcharts directly inside Claude, Cursor or other agents.474kLark SlidesInstantly generate polished, professional slide decks from specs, roadmaps, or meeting notes using Lark/Feishu.474kHow it compares
Choose gws-gmail-watch over manual Gmail API polling when you already use the gws CLI and want a ready-made NDJSON event stream.
FAQ
What command does gws-gmail-watch run?
gws-gmail-watch runs `gws gmail +watch`, which watches for new Gmail messages and prints each event as NDJSON on stdout. Consult `gws gmail +watch --help` for flags such as `--project` and `--subscription`.
What prerequisites does gws-gmail-watch need?
gws-gmail-watch requires the `gws` CLI binary and the gws-shared SKILL.md for OAuth and security rules. For Pub/Sub-backed watches, supply a GCP `--project` ID or an existing `--subscription` name.
Is Gws Gmail Watch safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.