gws-events-subscribe
googleworkspace/cli
Subscribe to Google Workspace events and stream them as NDJSON for real-time event processing.
What is gws-events-subscribe?
Subscribes to Google Workspace events (e.g., Chat messages, Drive changes) and streams them as NDJSON. Use this to monitor Workspace activity, trigger automations, or build event-driven workflows.
- Subscribe to specific Workspace resource events via CloudEvents types
- Stream events as NDJSON for easy parsing and processing
- Configure Pub/Sub integration with automatic or existing subscriptions
- Batch pull events with configurable intervals and message limits
- Optionally write each event to separate JSON files for archival
- Auto-acknowledge messages or disable acknowledgment for custom handling
How to install gws-events-subscribe
npx skills add null --skill gws-events-subscribe- Google Cloud project with Pub/Sub API enabled
- GCP credentials configured (see gws-shared SKILL.md)
- Workspace resource URI (e.g., //chat.googleapis.com/spaces/SPACE_ID)
- CloudEvents type identifiers for target events
How to use gws-events-subscribe
- 1.Run `gws events +subscribe --target '<resource-uri>' --event-types '<event-type>' --project '<gcp-project>'`
- 2.Monitor the NDJSON output stream for incoming events
- 3.Optionally use `--output-dir` to write events to separate JSON files
- 4.Press Ctrl-C to stop gracefully
- 5.Use `--cleanup` flag to delete Pub/Sub resources on exit, or omit to persist for reconnection
Use cases
- Monitor Chat messages in real-time and trigger workflows on new messages
- Track Drive file changes and sync them to external systems
- Stream Calendar events for scheduling automation
- Build audit logs by capturing all Workspace events to files
- Integrate Workspace events into custom applications via Pub/Sub
- Workspace administrators managing event-driven automations
- Developers building integrations with Google Workspace
- DevOps engineers setting up event monitoring and alerting
- Teams automating workflows based on Workspace activity
gws-events-subscribe FAQ
Events are streamed as NDJSON (newline-delimited JSON), with one complete event object per line for easy parsing.
No. The skill automatically creates Pub/Sub topic and subscription unless you provide an existing subscription name via `--subscription`.
Pub/Sub resources persist after the command exits, allowing you to reconnect later without recreating them.
Yes, use `--output-dir <path>` to write each event as a separate JSON file in that directory.
Event types follow CloudEvents format (e.g., `google.workspace.chat.message.v1.created`). Consult Google Workspace Events API documentation for your resource type.
Full instructions (SKILL.md)
Source of truth, from googleworkspace/cli.
name: gws-events-subscribe description: "Google Workspace Events: Subscribe to Workspace events and stream them as NDJSON." metadata: version: 0.22.5 openclaw: category: "productivity" requires: bins: - gws cliHelp: "gws events +subscribe --help"
events +subscribe
PREREQUISITE: Read
../gws-shared/SKILL.mdfor auth, global flags, and security rules. If missing, rungws generate-skillsto create it.
Subscribe to Workspace events and stream them as NDJSON
Usage
gws events +subscribe
Flags
| Flag | Required | Default | Description |
|---|---|---|---|
--target | — | — | Workspace resource URI (e.g., //chat.googleapis.com/spaces/SPACE_ID) |
--event-types | — | — | Comma-separated CloudEvents types to subscribe to |
--project | — | — | GCP project ID for Pub/Sub resources |
--subscription | — | — | Existing Pub/Sub subscription name (skip setup) |
--max-messages | — | 10 | Max messages per pull batch (default: 10) |
--poll-interval | — | 5 | Seconds between pulls (default: 5) |
--once | — | — | Pull once and exit |
--cleanup | — | — | Delete created Pub/Sub resources on exit |
--no-ack | — | — | Don't auto-acknowledge messages |
--output-dir | — | — | Write each event to a separate JSON file in this directory |
Examples
gws events +subscribe --target '//chat.googleapis.com/spaces/SPACE' --event-types 'google.workspace.chat.message.v1.created' --project my-project
gws events +subscribe --subscription projects/p/subscriptions/my-sub --once
gws events +subscribe ... --cleanup --output-dir ./events
Tips
- Without --cleanup, Pub/Sub resources persist for reconnection.
- Press Ctrl-C to stop gracefully.
[!CAUTION] This is a write command — confirm with the user before executing.
See Also
- gws-shared — Global flags and auth
- gws-events — All subscribe to google workspace events commands
Related skills
More from googleworkspace/cli and the wider catalog.
gws-gmail
Send, read, and manage Gmail emails via Google Workspace CLI.
gws-drive
Manage Google Drive files, folders, and shared drives via CLI.
gws-docs
Read and write Google Docs via command line.
gws-calendar
Manage Google Calendar events, calendars, and access control via CLI.
gws-sheets
Read and write Google Sheets spreadsheets via CLI.
gws-gmail-send
Send emails via Gmail with attachments, CC/BCC, HTML support, and draft options.