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