it2 subscribe
Subscribe to iTerm2 notifications
Synopsis
it2 subscribe [flags]
Description
Subscribe to iTerm2 notifications and output raw events as NDJSON.
This is a low-level tool for subscribing to global and session-specific notifications.
For session-specific monitoring with enhanced output, use 'it2 session monitor' instead.
Global event types (no --session required): [new-session terminate-session layout-change focus-change server-rpc broadcast-change profile-change]
- new-session: New sessions created
- terminate-session: Sessions terminated
- layout-change: Window/tab layout changes
- focus-change: Focus changes between sessions
- server-rpc: Server-originated RPC calls
- broadcast-change: Broadcast domain changes
- profile-change: Profile changes
Session-specific event types (requires --session): [prompt keystroke screen variable escape]
- prompt: Shell prompt changes (requires Shell Integration)
- keystroke: Individual keystrokes
- screen: Screen content updates
- variable: Session variable changes
- escape: Custom escape sequences
Special keywords:
- all: Subscribe to all event types
Multiple event types can be specified with comma-separated values.
The command outputs raw protobuf notifications as compact JSON, one per line.
Use Ctrl+C to stop.
Options
-
--events - Event types to subscribe to: prompt, keystroke, screen, variable, escape, new-session, terminate-session, layout-change, focus-change, server-rpc, broadcast-change, profile-change, or 'all'
-
--session - Session ID to monitor (optional, for session-specific events)
Options inherited from parent commands
-
--format(default "text") - Output format (text, json, yaml) - affects how command results are displayed
-
--timeout - Timeout for API operations - how long to wait for iTerm2 to respond
-
--url - WebSocket URL for iTerm2 API - typically ws://localhost:1912 for local iTerm2
See Also
- it2 - iTerm2 API Command-Line Interface
Examples
# Global notifications
it2 subscribe --events new-session,terminate-session
# Session-specific notifications
it2 subscribe --session $SID --events prompt,keystroke
# All global events
it2 subscribe --events all