vellum-ai Create and manage watchers that poll external services for events and process them with an action prompt.
Concepts
- Provider - The external service to poll (e.g. "gmail"). Each provider defines how to fetch and parse events.
- Action prompt - LLM instructions for handling detected events. Sent along with event data to a background conversation.
- Poll interval - How often to check for new events (minimum 15 seconds, default 60 seconds).
- Digest - Summary of recent watcher activity, grouped by watcher with time-based filtering.
Lifecycle
- Create a watcher with
assistant watchers create, specifying a name, provider, and action prompt. - The system polls the provider at the configured interval.
- Detected events are processed according to the action prompt.
- Use
assistant watchers digestto review recent activity.
Available Commands
Create a watcher
assistant watchers create \
--name <name> \
--provider <provider> \
--action-prompt <prompt> \
[--poll-interval <ms>] \
[--config <json>] \
[--credential-service <service>]
| Flag | Required | Description |
|---|---|---|
--name |
Yes | A human-readable name for this watcher (e.g. "My Gmail") |
--provider |
Yes | The provider to poll (see Available Providers below) |
--action-prompt |
Yes | Instructions for the LLM on how to handle detected events |
--poll-interval |
No | How often to poll in milliseconds. Defaults to 60000 (1 minute). Minimum 15000 |
--config |
No | Provider-specific configuration as JSON (e.g. filter criteria) |
--credential-service |
No | Override the credential service to use. Defaults to the provider's required service |
Example:
assistant watchers create \
--name "My Gmail" \
--provider gmail \
--action-prompt "Summarize new emails and notify me if anything is urgent"
List watchers
assistant watchers list [--id <watcherId>] [--enabled-only]
| Flag | Required | Description |
|---|---|---|
--id |
No | Show detailed info for a specific watcher including recent events |
--enabled-only |
No | Only show enabled watchers |
Example:
# List all watchers
assistant watchers list
# Show details for a specific watcher
assistant watchers list --id abc123
Update a watcher
assistant watchers update <watcherId> \
[--name <name>] \
[--action-prompt <prompt>] \
[--poll-interval <ms>] \
[--enabled | --disabled] \
[--config <json>]
| Flag | Required | Description |
|---|---|---|
<watcherId> |
Yes | The ID of the watcher to update (positional argument) |
--name |
No | New name for the watcher |
--action-prompt |
No | New action prompt for event processing |
--poll-interval |
No | New poll interval in milliseconds (minimum 15000) |
--enabled |
No | Enable the watcher |
--disabled |
No | Disable the watcher |
--config |
No | New provider-specific configuration as JSON |
Example:
# Change the action prompt
assistant watchers update abc123 --action-prompt "Flag urgent emails and ignore newsletters"
# Disable a watcher temporarily
assistant watchers update abc123 --disabled
Delete a watcher
assistant watchers delete <watcherId>
Permanently deletes a watcher and all its event history.
Example:
assistant watchers delete abc123
View watcher digest
assistant watchers digest [--id <watcherId>] [--hours <n>] [--limit <n>]
| Flag | Required | Description |
|---|---|---|
--id |
No | Filter to events from a specific watcher. If omitted, shows events from all watchers |
--hours |
No | How many hours back to look. Defaults to 24 |
--limit |
No | Maximum number of events to return. Defaults to 50 |
Example:
# See all watcher activity from the last 24 hours
assistant watchers digest
# See activity from a specific watcher over the last 8 hours
assistant watchers digest --id abc123 --hours 8
Available Providers
| Provider | Description |
|---|---|
gmail |
Monitor a Gmail inbox for new emails |
google-calendar |
Monitor Google Calendar for new or updated events |
github |
Monitor GitHub for repository activity |
linear |
Monitor Linear for issue updates |
outlook |
Monitor an Outlook inbox for new emails |
outlook-calendar |
Monitor Outlook Calendar for new or updated events |
Usage Notes
- Use
assistant watchers createwhen the user wants to monitor an external source (e.g. "watch my Gmail for important emails"). assistant watchers digestis the go-to command when the user asks "what happened with my email?" or similar questions about watcher activity.- Watchers can be enabled/disabled via
assistant watchers updatewithout deleting them -- use--disabledto pause and--enabledto resume. - Each provider requires appropriate credentials to be configured. The
--credential-serviceflag can override the default credential service if needed. - Notify only when the action prompt's match criteria are met. Unmatched events stay quiet: do not send a notification whose only content is that nothing matched. Watcher ticks are not scheduled runs.