Skip to content

watch.md

Latest commit

 

History

History
153 lines (107 loc) · 7.08 KB

watch.md

File metadata and controls

153 lines (107 loc) · 7.08 KB
Raw

Watch Commands

Monitor your mailbox and calendar for changes in real-time. Watch mode uses Microsoft Graph delta queries to efficiently detect new or modified items without re-downloading everything.

The watch command accepts global options (--account, --format, --json, --output, --verbose).

For deep technical details on delta tokens, adaptive polling, webhook architecture, and multi-job configuration, see WATCH-MODE.md.

watch

Start watching for changes. By default, polls every 60 seconds for both mail and calendar changes.

# Default: poll every 60 seconds
outlook-cli watch

# Watch mail only, 30-second interval
outlook-cli watch --no-calendar --interval 30

# JSONL output for piping to an agent or script
outlook-cli watch --jsonl | my-agent-process

# Fast-poll mode for near-instant response (5-60s adaptive)
outlook-cli watch --mode fast-poll --interval 10

# Webhook mode for true push notifications (~1-5s latency)
outlook-cli watch --mode webhook

# Watch a specific folder
outlook-cli watch --folder "Important" --no-calendar

# Multi-job rules engine
outlook-cli watch --config watch-rules.json

# Validate config without starting
outlook-cli watch --config watch-rules.json --validate
Option Description Default
--mode <mode> Notification mode. poll checks at a fixed interval. fast-poll uses adaptive polling that speeds up during activity and slows during quiet periods. webhook uses Microsoft Graph push notifications via a tunnel for near-instant delivery. poll
--interval <seconds> Poll interval in seconds. Minimum is 30 for poll mode, 5 for fast-poll. In fast-poll mode, this is the maximum interval — the watcher drops to 5s when activity is detected. 60
--no-mail Don't watch for mail changes. Watch both
--no-calendar Don't watch for calendar changes. Watch both
--folder <name> Mail folder to watch. Uses the display name (e.g., Inbox, Important, Sent Items). Inbox
--jsonl Output each change event as a JSON Lines object (one JSON object per line). Essential for agent/script integration — each line is independently parseable. Text output
--heartbeat Emit periodic heartbeat events so consuming processes know the watcher is alive. Without this, there's no output during quiet periods. No heartbeats
--heartbeat-interval <seconds> How often to emit heartbeat events. Only relevant when --heartbeat is enabled. 300 (5 minutes)
--tunnel <type> Tunnel provider for webhook mode. Options: cloudflared (free, no account needed), ngrok (requires account), localtunnel (free, less reliable). cloudflared
--webhook-port <port> Local port for the webhook HTTP server. If you have a public IP/reverse proxy, you can skip the tunnel and expose this port directly. Random available port
--config <path> Path to a watch configuration JSON file. Enables the multi-job rules engine with independent watches, conditions, and actions. See WATCH-MODE.md for the config schema. —
--validate Validate the config file syntax and exit without starting the watch. Requires --config. —

Watch Modes Compared

Mode Latency API Calls Setup Best For
poll 30-60 seconds Low (1 call/interval) None Notifications, casual monitoring
fast-poll 5-60 seconds (adaptive) Medium (more during activity) None Agent integration without infrastructure
webhook 1-5 seconds Very low (push-based) Tunnel or public IP Real-time gateways, critical response

Poll Mode (Default)

Makes a delta query every --interval seconds. Delta queries only return items that changed since the last call, so even with a large mailbox, each poll transfers minimal data. Simple and reliable, but has inherent latency equal to the polling interval.

Fast-Poll Mode

Same delta queries but with adaptive frequency:

  • Starts at the configured --interval
  • When changes are detected: drops to 5-second polling to catch follow-up messages
  • When no changes are found: backs off by 1.5× each cycle (5s → 7.5s → 11s → 17s → 25s → ... up to max)
  • Resets to 5s immediately when any change arrives

This gives near-instant response during active conversations while conserving API quota during quiet periods. Ideal for AI agent integration without requiring tunnel infrastructure.

Webhook Mode

Uses Microsoft Graph subscriptions to receive push notifications. The CLI starts a local HTTP server and creates a tunnel (via cloudflared, ngrok, or localtunnel) to make it reachable from the internet:

Microsoft Graph ──POST──→ Tunnel (cloudflared) ──→ localhost:PORT ──→ outlook-cli

Webhook mode has the lowest latency (~1-5 seconds) but requires either a tunnel tool installed or a publicly accessible port. The CLI manages the subscription lifecycle automatically (creation, renewal every ~15 minutes, cleanup on exit).

Note: Webhook mode is only available in the Node.js implementation. The C# binary falls back to fast-poll with a message explaining this.

Output Formats

Text Output (Default)

[2026-01-15 09:30:05] 📬 New mail from alice@example.com: "Quarterly Report"
[2026-01-15 09:35:12] 📬 New mail from bob@example.com: "Re: Meeting Notes"
[2026-01-15 10:00:00] 📅 Calendar: "Team Standup" starting now

JSONL Output (--jsonl)

Each event is a single-line JSON object:

{"type":"mail","action":"created","id":"AAMkAD...","subject":"Quarterly Report","from":"alice@example.com","receivedDateTime":"2026-01-15T09:30:05Z","timestamp":"2026-01-15T09:30:06Z"}
{"type":"mail","action":"created","id":"AAMkAD...","subject":"Re: Meeting Notes","from":"bob@example.com","receivedDateTime":"2026-01-15T09:35:12Z","timestamp":"2026-01-15T09:35:13Z"}
{"type":"heartbeat","timestamp":"2026-01-15T09:40:00Z","uptime":600}

JSONL is the recommended format for agent and script integration. Each line can be parsed independently, and heartbeat events let consuming processes detect if the watcher is still alive.

Common Workflows

Pipe to an agent

outlook-cli watch --mode fast-poll --jsonl --heartbeat | while read -r line; do
    echo "$line" | my-agent --process-event
done

Monitor and log to a file

outlook-cli watch --jsonl --output events.jsonl
# In another terminal:
tail -f events.jsonl

Watch with rules (multi-job)

# Create a config file (see WATCH-MODE.md for schema)
outlook-cli watch --config watches.json

# Validate first
outlook-cli watch --config watches.json --validate

Stopping the Watch

Press Ctrl+C to stop. The watcher:

  1. Saves the current delta token (so next start picks up where it left off)
  2. Cancels any pending Graph API requests
  3. In webhook mode: deletes the subscription and closes the tunnel
  4. Exits cleanly with code 0

Delta tokens are saved to ~/.outlook-cli/delta-{alias}.json and survive restarts. The next watch start only reports changes that happened while it was stopped.