Project gnachman/iTerm2

oneof identifier
To activate the app without changing anything else omit the identifier.
- string window_id = 1
- string tab_id = 2
- string session_id = 3
optional bool order_window_front = 4
optional bool select_tab = 5
This may be enabled if tab_id or session_id is set.
optional bool select_session = 6
This may be enabled if session_id is set.
optional ActivateRequest.App activate_app = 7

Activate the app?

Used in: ActivateRequest

optional bool raise_all_windows = 1
optional bool ignoring_other_apps = 2

optional ActivateResponse.Status status = 1

Used in: ActivateResponse

OK = 0
BAD_IDENTIFIER = 1
INVALID_OPTION = 2

Used in: CellStyle

DEFAULT = 0
REVERSED_DEFAULT = 3
SYSTEM_MESSAGE = 4

Used in: BroadcastDomainsChangedNotification, GetBroadcastDomainsResponse, SetBroadcastDomainsRequest

repeated string session_ids = 1

Used in: Notification

repeated BroadcastDomain broadcast_domains = 1

Used in: LineContents

oneof fgColor
- uint32 fgStandard = 1
- AlternateColor fgAlternate = 2
- RGBColor fgRgb = 3
- uint32 fgAlternatePlacementX = 4
oneof bgColor
- uint32 bgStandard = 5
- AlternateColor bgAlternate = 6
- RGBColor bgRgb = 7
- uint32 bgAlternatePlacementY = 8
optional bool bold = 9
optional bool faint = 10
optional bool italic = 11
optional bool blink = 12
optional bool underline = 13
optional bool strikethrough = 14
optional bool invisible = 15
optional bool inverse = 16
optional bool guarded = 17
optional ImagePlaceholderType image = 18
optional RGBColor underlineColor = 19
External attributes
optional string blockID = 20
optional URL url = 21
optional uint32 repeats = 22
Number of times this exact style repeats.

All requests are wrapped in this message. This encoded message is the entirety of the payload of messages sent over WebSocket from client to iTerm2.

optional int64 id = 1
oneof submessage
- GetBufferRequest get_buffer_request = 100
- GetPromptRequest get_prompt_request = 101
- TransactionRequest transaction_request = 102
- NotificationRequest notification_request = 103
- RegisterToolRequest register_tool_request = 104
- SetProfilePropertyRequest set_profile_property_request = 105
- ListSessionsRequest list_sessions_request = 106
- SendTextRequest send_text_request = 107
- CreateTabRequest create_tab_request = 108
- SplitPaneRequest split_pane_request = 109
- GetProfilePropertyRequest get_profile_property_request = 110
- SetPropertyRequest set_property_request = 111
- GetPropertyRequest get_property_request = 112
- InjectRequest inject_request = 113
- ActivateRequest activate_request = 114
- VariableRequest variable_request = 115
- SavedArrangementRequest saved_arrangement_request = 116
- FocusRequest focus_request = 117
- ListProfilesRequest list_profiles_request = 118
- ServerOriginatedRPCResultRequest server_originated_rpc_result_request = 119
- RestartSessionRequest restart_session_request = 120
- MenuItemRequest menu_item_request = 121
- SetTabLayoutRequest set_tab_layout_request = 122
- GetBroadcastDomainsRequest get_broadcast_domains_request = 123
- TmuxRequest tmux_request = 124
- ReorderTabsRequest reorder_tabs_request = 125
- PreferencesRequest preferences_request = 126
- ColorPresetRequest color_preset_request = 127
- SelectionRequest selection_request = 128
- StatusBarComponentRequest status_bar_component_request = 129
- SetBroadcastDomainsRequest set_broadcast_domains_request = 130
- CloseRequest close_request = 131
- InvokeFunctionRequest invoke_function_request = 132
- ListPromptsRequest list_prompts_request = 133

oneof target
- CloseRequest.CloseTabs tabs = 1
- CloseRequest.CloseSessions sessions = 2
- CloseRequest.CloseWindows windows = 3
optional bool force = 4

Used in: CloseRequest

repeated string session_ids = 1

Used in: CloseRequest

repeated string tab_ids = 1

Used in: CloseRequest

repeated string window_ids = 1

repeated CloseResponse.Status statuses = 1

Used in: CloseResponse

OK = 0
NOT_FOUND = 1
USER_DECLINED = 2

Used in: LineContents

optional int32 num_code_points = 1
Number of code points per cell
optional int32 repeats = 2
Number of adjacent cells with this number of code points (always one or more).

oneof request
- ColorPresetRequest.ListPresets list_presets = 1
- ColorPresetRequest.GetPreset get_preset = 2

Used in: ColorPresetRequest

optional string name = 1

Used in: ColorPresetRequest

(message has no fields)

oneof response
- ColorPresetResponse.ListPresets list_presets = 1
- ColorPresetResponse.GetPreset get_preset = 2
optional ColorPresetResponse.Status status = 3

Used in: ColorPresetResponse

repeated GetPreset.ColorSetting color_settings = 1

Used in: GetPreset

optional float red = 1
optional float green = 2
optional float blue = 3
optional float alpha = 4
optional string color_space = 5
optional string key = 6

Used in: ColorPresetResponse

repeated string name = 1

Used in: ColorPresetResponse

OK = 0
PRESET_NOT_FOUND = 1
REQUEST_MALFORMED = 2

Describes a cell's location.

Used in: CoordRange, GetBufferResponse

optional int32 x = 1
optional int64 y = 2
y=0 describes the first line. When the scrollback buffer is full and history is lost, the first lines become unavailable, but the numbering is stable (so the Nth line is always the Nth line, even if it's not the Nth *visible* line).

Describes a range of cells. |..xxxxx| |xxxx...| In the example above, the range of x's is: {start: {x:2, y:0}, end: {x:4, y:1}} The end coordinate is the first cell *after* the end of the range described (so an empty range has start == end)

Used in: GetPromptResponse, WindowedCoordRange

optional Coord start = 1
optional Coord end = 2

optional string profile_name = 1
Leave unset to use the default profile.
optional string window_id = 2
Leave unset to create the tab in a new window.
optional uint32 tab_index = 3
Valid to set only if window_id is set. Gives the desired index of the new tab.
optional string command = 4
If not set, the profile's command will be used. Use custom_profile_properties instead.
repeated ProfileProperty custom_profile_properties = 5
Modifies the profile to customize its behavior just for this session.

optional CreateTabResponse.Status status = 1
optional string window_id = 2
optional int32 tab_id = 3
optional string session_id = 4

Used in: CreateTabResponse

OK = 0
INVALID_PROFILE_NAME = 1
INVALID_WINDOW_ID = 2
INVALID_TAB_INDEX = 3
The tab is still created, just not with the desired index.
MISSING_SUBSTITUTION = 4
A $$VAR$$ substitution was not provided by the user.

OSC 1337 ; Custom=id=<identity>:<payload> ST

Used in: Notification

optional string session = 1
optional string sender_identity = 2
optional string payload = 3

Note this is sent when the app becomes/resigns active, the key window changes, the selected tab of a window changes, or the active pane of a tab changes. Note that you may receive duplicate notifications at times. Ignore those that do not signify a change.

Used in: FocusResponse, Notification

oneof event
- bool application_active = 1
  true: application became active. false: application resigned active.
- FocusChangedNotification.Window window = 2
  If set, gives info about a change to window focus.
- string selected_tab = 3
  If set, selected tab changed to the one identified herein.
- string session = 4
  If set, the given session became active in its tab.

Used in: FocusChangedNotification

optional Window.WindowStatus window_status = 1
Describes how to interpret window_id.
optional string window_id = 2
The affected window_id

Used in: Window

TERMINAL_WINDOW_BECAME_KEY = 0
`window_id` became key
TERMINAL_WINDOW_IS_CURRENT = 1
`window_id` is not key, but is the current terminal window. Some other non-terminal window is key.
TERMINAL_WINDOW_RESIGNED_KEY = 2
`window_id` is no longer key.

(message has no fields)

repeated FocusChangedNotification notifications = 1
A collection of notifications that completely describe the state of every tab and window and the application itself.

Used in: ListSessionsResponse.Window, SessionSummary

optional Point origin = 1
optional Size size = 2

(message has no fields)

repeated BroadcastDomain broadcast_domains = 1

Requests the contents of a range of lines.

optional string session = 1
See documentation on session IDs. "all" not accepted.
optional LineRange line_range = 2
Which lines to return?
optional bool include_styles = 3
Populate `style` field of `LineContents`?

Contains the contents of a range of lines.

optional GetBufferResponse.Status status = 1
optional Range range = 2
Which lines were returned
repeated LineContents contents = 3
Those lines' contents.
optional Coord cursor = 4
optional int64 num_lines_above_screen = 5
The number of lines (including lines lost from the head of scrollback history) that precede the screen. Subtract this from cursor.y to get the cursor's position on the screen when it is scrolled to the bottom.
optional WindowedCoordRange windowed_coord_range = 6
The returned range

Used in: GetBufferResponse

OK = 0
SESSION_NOT_FOUND = 1
INVALID_LINE_RANGE = 2
REQUEST_MALFORMED = 3

optional string session = 1
See documentation on session IDs
repeated string keys = 2
If not set, all properties will be returned

optional GetProfilePropertyResponse.Status status = 1
repeated ProfileProperty properties = 3

Used in: GetProfilePropertyResponse

OK = 0
SESSION_NOT_FOUND = 1
REQUEST_MALFORMED = 2
ERROR = 3

Requests metadata about the current shell prompt.

optional string session = 1
See documentation on session IDs. "all" not accepted.
optional string unique_prompt_id = 2
If given return this ID instead of the last one.

Responds with metadata about the current shell prompt, if possible.

Used in: PromptNotificationPrompt, ServerOriginatedMessage

optional GetPromptResponse.Status status = 1
optional CoordRange prompt_range = 2
optional CoordRange command_range = 3
optional CoordRange output_range = 4
optional string working_directory = 5
optional string command = 6
optional GetPromptResponse.State prompt_state = 7
optional uint32 exit_status = 9
Exit status. Equivalent to shell's $? variable. Only set if state is FINISHED.
optional string unique_prompt_id = 10

Used in: GetPromptResponse

EDITING = 0
Command hasn't been started yet
RUNNING = 1
Command is currently running
FINISHED = 2
Command has finished.

Used in: GetPromptResponse

OK = 0
SESSION_NOT_FOUND = 1
REQUEST_MALFORMED = 2
PROMPT_UNAVAILABLE = 3

oneof identifier
The kind of ID that's set determines the kind of object you're querying.
- string window_id = 1
- string session_id = 3
  Does not accept "all". Accepts "active".
optional string name = 2
For sessions: "grid_size" -> { "width": number, "height": number } "buried" -> boolean "number_of_lines" -> { "overflow": number, "grid": number, "history": number } For windows: "frame" -> { "origin": { "x": number, "y": number }, "size": { "width": number, "height": number } } "fullscreen" -> boolean

optional GetPropertyResponse.Status status = 1
Name Example value ------------- --------------- frame { "origin": { "x": 0, "y": 0 }, "size": { "width": 1024, "height": 768 }} fullscreen true, false For sessions: grid_size { "width": 80, "height": 25 } buried true
optional string json_value = 2

Used in: GetPropertyResponse

OK = 0
UNRECOGNIZED_NAME = 1
INVALID_TARGET = 2

Used in: CellStyle

NONE = 0
ITERM2 = 1
KITTY = 2

Injects bytes as input to the terminal, as though the running program had produced them.

repeated string session_id = 1
optional bytes data = 2

repeated InjectResponse.Status status = 1
One status per session_id in the request

Used in: InjectResponse

OK = 0
SESSION_NOT_FOUND = 1

oneof context
- InvokeFunctionRequest.Tab tab = 1
- InvokeFunctionRequest.Session session = 2
- InvokeFunctionRequest.Window window = 3
- InvokeFunctionRequest.App app = 4
- InvokeFunctionRequest.Method method = 7
optional string invocation = 5
optional double timeout = 6
If not given a reasonable default value will be used. Negative value means to use the default.

(message has no fields)

optional string receiver = 1
The following methods are defined: window.set_title(title: String) session.set_name(name: String) session.run_tmux_command(command: String) throws // Throws an exception if this is not a tmux session session.set_status_bar_component_unread_count(identifier: String, count: Int) session.stop_coprocess() -> Bool // returns whether there was a coprocess to stop session.get_coprocess() -> String? // returns the name of the command, or nil session.run_coprocess(commandLine: String, mute: Bool) -> Bool // returns whether it attempted to start the coprocess. It'll fail only if there is already a coprocess. tab.set_title(title: String) tab.select_pane_in_direction(direction: String) throws -> String // direction is 'left', 'right', 'above', or 'below'. If successful, it will return the ID of the newly active session. If you can't go that way, it returns null. Throws an exception if the direction is invalid.

optional string session_id = 1

optional string tab_id = 1

optional string window_id = 1

oneof disposition
- InvokeFunctionResponse.Error error = 1
- InvokeFunctionResponse.Success success = 2

Used in: InvokeFunctionResponse

optional Status status = 1
optional string error_reason = 2

Used in: Error

TIMEOUT = 1
FAILED = 2
REQUEST_MALFORMED = 3
INVALID_ID = 4

Used in: InvokeFunctionResponse

optional string json_result = 1

Used in: NotificationRequest

repeated KeystrokePattern patterns_to_ignore = 1
If a keystroke matches any of these patterns then they will not be handled by the application. A notification will be posted and the script can handle it as it pleases.

Used in: NotificationRequest

repeated KeystrokePattern patterns_to_ignore = 1
KeystrokeFilterRequest was split from this to make a more sensible API.
optional bool advanced = 2
If false, then only key-down events are sent. If true, key-down, key-up, and flags-changed events are sent.

Used in: Notification

optional string characters = 1
optional string charactersIgnoringModifiers = 2
repeated Modifiers modifiers = 3
optional int32 keyCode = 4
optional string session = 5
optional KeystrokeNotification.Action action = 6

Used in: KeystrokeNotification

KEY_DOWN = 0
These are used for non-modifier keys.
KEY_UP = 1
requires advanced=true in request
FLAGS_CHANGED = 2
This is used when only a modifier changes.
requires advanced=true in request

Used in: KeystrokeFilterRequest, KeystrokeMonitorRequest

repeated Modifiers required_modifiers = 1
The keystroke matches the pattern if it has all the required and none of the forbidden modifiers.
repeated Modifiers forbidden_modifiers = 2
repeated int32 keycodes = 3
The pattern matches if the keystroke has any of these keycodes:
repeated string characters = 4
The pattern matches if the keystroke equals of any of these characters:
repeated string characters_ignoring_modifiers = 5
The pattern matches if the keystroke equals any of these characters ignoring modifiers. This is Apple parlance for "ignoring the shift key plus various other undocumented things"

Used in: Notification

optional ListSessionsResponse list_sessions_response = 1

Describes the content of a line.

Used in: GetBufferResponse

optional string text = 1
repeated CodePointsPerCell code_points_per_cell = 2
Some cells do not contain one code point. Use this to map code points in `text` to a screen position. If the line has no uninitialized cells at its end, then the sum of `repeats` equals the width of the display. For example, consider a line of text that appears on your display like: xyz compañía The corresponding value of `text` would be: xyzcompan~i'a Note: ~ and ' are combining marks, but are shown uncombined for illustrative purposes. Each code point in "xyz" as well as each of the non-accented letters in compañía takes one cell. The blank following 'z' is an uninitialized cell that has no code points, so the z and the c in `text` are adjacent. It's unusual for these to occur in the middle of a line, but it is possible. The ñ is composed of the letter n and a combining tilde (U+0303) (indicated in our example as ~), while í is composed of the letter i and a combining acute accent (U+0301) (indicated in our example as '). To map code points in `text` to screen positions, `code_points_per_cell` provides the number of code points in each cell. In our example you would get: num_code_points=1, repeats=3 // x, y, z num_code_points=0, repeats=1 // uninitialized cell num_code_points=1, repeats=5 // c, o, m, p, a num_code_points=2, repeats=2 // n + combining tilde, i + combining acute accent num_code_points=1, repeats=1 // a Lines usually end with a series of uninitialized cells. These are not included. Here is psuedocode to interpret code_points_per_cell: text_index_to_screen_coord = {} screen_coord_to_text_index = {} text_index = 0 screen_coord = 0 for cpps in code_points_per_cell: repeat cpps.repeats times: text_index_to_screen_coord[text_index] = screen_coord screen_coord_to_text_index[screen_coord] = text_index text_index += cpps.num_code_points screen_coord += 1 Cells with images are omitted.
optional LineContents.Continuation continuation = 3
repeated CellStyle style = 4
This will be 1:1 with cells, but it is run-length encoded by its `repeats` field.

How does this line end?

Used in: LineContents

CONTINUATION_HARD_EOL = 1
This line is not wrapped.
CONTINUATION_SOFT_EOL = 2
The next line is a continuation of this line.

Describes a range of lines.

Used in: GetBufferRequest

optional bool screen_contents_only = 1
Only one of these fields should be set: --------------------------------------- Return just the current contents of the screen.
optional int32 trailing_lines = 2
Return the last `trailing lines` of the buffer, which could go back into scrollback history.
optional WindowedCoordRange windowed_coord_range = 3

Requests a list of all profiles.

repeated string properties = 1
The profile properties to respond with. See SetProfilePropertyRequest for a list of values. If empty, all properties will be returned.
repeated string guids = 2
If empty, all profiles will be returned. Otherwise, only profiles with one of the listed GUIDs will be returned.

repeated ListProfilesResponse.Profile profiles = 1

Used in: ListProfilesResponse

repeated ProfileProperty properties = 1

optional string session = 1
Must name a specific session. "all" not allowed.
optional string first_unique_id = 2
If unspecified, start at oldest.
optional string last_unique_id = 3
If unspecified, end at newest.

optional ListPromptsResponse.Status status = 1
repeated string unique_prompt_id = 2
Chronological list of prompt IDs, suitable for GetPromptRequest.unique_prompt_id.

Used in: ListPromptsResponse

OK = 0
SESSION_NOT_FOUND = 1

(message has no fields)

Used in: LayoutChangedNotification, ServerOriginatedMessage

repeated ListSessionsResponse.Window windows = 1
repeated SessionSummary buried_sessions = 2

Used in: Window

optional SplitTreeNode root = 3
optional string tab_id = 2
optional string tmux_window_id = 4
optional string tmux_connection_id = 5
repeated SessionSummary minimized_sessions = 6

Used in: ListSessionsResponse

repeated Tab tabs = 1
optional string window_id = 2
optional Frame frame = 3
optional int32 number = 4

Used in: Notification

optional string host_name = 1
optional string user_name = 2
optional string directory = 3
optional string session = 4

Invoke or ask for info about a menu item

optional string identifier = 1
Unique identifier of the menu item.
optional bool query_only = 2
If set do not actually invoke it. Just return its state.

optional MenuItemResponse.Status status = 1
optional bool checked = 2
optional bool enabled = 3

Used in: MenuItemResponse

OK = 0
BAD_IDENTIFIER = 1
DISABLED = 2

Used in: KeystrokeNotification, KeystrokePattern

CONTROL = 1
OPTION = 2
COMMAND = 3
SHIFT = 4
FUNCTION = 5
NUMPAD = 6

Sent when a new session is created or a closure is undone.

Used in: Notification

optional string session_id = 1

optional KeystrokeNotification keystroke_notification = 1
optional ScreenUpdateNotification screen_update_notification = 2
optional PromptNotification prompt_notification = 3
optional LocationChangeNotification location_change_notification = 4
optional CustomEscapeSequenceNotification custom_escape_sequence_notification = 5
optional NewSessionNotification new_session_notification = 6
optional TerminateSessionNotification terminate_session_notification = 7
optional LayoutChangedNotification layout_changed_notification = 8
optional FocusChangedNotification focus_changed_notification = 9
optional ServerOriginatedRPCNotification server_originated_rpc_notification = 10
optional BroadcastDomainsChangedNotification broadcast_domains_changed = 11
optional VariableChangedNotification variable_changed_notification = 12
optional ProfileChangedNotification profile_changed_notification = 13

optional string session = 1
See documentation on session IDs. NOTIFY_ON_NEW_SESSION, NOTIFY_ON_TERMINATE_SESSION, and NOTIFY_ON_LAYOUT_CHANGE do not use the session ID and are posted on all such events. NOTE: This is not used for NOTIFY_ON_VARIABLE_CHANGE.
optional bool subscribe = 2
Set to true to subscribe, false to unsubscribe.
optional NotificationType notification_type = 3
When to be notified (or notification to unsubscribe from)
oneof arguments
- RPCRegistrationRequest rpc_registration_request = 4
  For NOTIFY_ON_SERVER_ORIGINATED_RPC
- KeystrokeMonitorRequest keystroke_monitor_request = 5
- VariableMonitorRequest variable_monitor_request = 6
- ProfileChangeRequest profile_change_request = 7
- KeystrokeFilterRequest keystroke_filter_request = 8
- PromptMonitorRequest prompt_monitor_request = 9

optional NotificationResponse.Status status = 1

Used in: NotificationResponse

OK = 0
SESSION_NOT_FOUND = 1
REQUEST_MALFORMED = 2
NOT_SUBSCRIBED = 3
ALREADY_SUBSCRIBED = 4
DUPLICATE_SERVER_ORIGINATED_RPC = 5
INVALID_IDENTIFIER = 6

Used in: NotificationRequest

NOTIFY_ON_KEYSTROKE = 1
Notifications that use the `session` parameter.
NOTIFY_ON_SCREEN_UPDATE = 2
NOTIFY_ON_PROMPT = 3
NOTIFY_ON_LOCATION_CHANGE = 4
NOTIFY_ON_CUSTOM_ESCAPE_SEQUENCE = 5
NOTIFY_ON_VARIABLE_CHANGE = 12
KEYSTROKE_FILTER = 14
Does not send a notification
NOTIFY_ON_NEW_SESSION = 6
Notifications that ignore the `session` parameter.
NOTIFY_ON_TERMINATE_SESSION = 7
NOTIFY_ON_LAYOUT_CHANGE = 8
NOTIFY_ON_FOCUS_CHANGE = 9
NOTIFY_ON_SERVER_ORIGINATED_RPC = 10
NOTIFY_ON_BROADCAST_CHANGE = 11
NOTIFY_ON_PROFILE_CHANGE = 13

Used in: Frame

optional int32 x = 1
optional int32 y = 2

repeated PreferencesRequest.Request requests = 1

Used in: PreferencesRequest

oneof request
- Request.SetPreference set_preference_request = 1
- Request.GetPreference get_preference_request = 2
- Request.SetDefaultProfile set_default_profile_request = 3
- Request.GetDefaultProfile get_default_profile_request = 4

Used in: Request

(message has no fields)

Used in: Request

optional string key = 1

Used in: Request

optional string guid = 1

Used in: Request

optional string key = 1
optional string json_value = 2

repeated PreferencesResponse.Result results = 1

Used in: PreferencesResponse

oneof result
- Result.UnrecognizedResult unrecognized_request = 1
- Result.SetPreferenceResult set_preference_result = 2
- Result.GetPreferenceResult get_preference_result = 3
- Result.SetDefaultProfileResult set_default_profile_result = 4
- Result.GetDefaultProfileResult get_default_profile_result = 5

Used in: Result

optional string guid = 1

Used in: Result

optional string json_value = 1
Will be unset if no value assigned. Will always be set if there is a default value.

Used in: Result

optional SetDefaultProfileResult.Status status = 1

Used in: SetDefaultProfileResult

OK = 0
BAD_GUID = 1

Used in: Result

optional SetPreferenceResult.Status status = 1

Used in: SetPreferenceResult

OK = 0
BAD_JSON = 1
INVALID_VALUE = 2
Not legal for a plist

Used in: Result

(message has no fields)

Used in: NotificationRequest

optional string guid = 1

Used in: Notification

optional string guid = 1

Used in: CreateTabRequest, GetProfilePropertyResponse, ListProfilesResponse.Profile, SplitPaneRequest

optional string key = 1
optional string json_value = 2

Used in: PromptMonitorRequest

PROMPT = 1
COMMAND_START = 2
COMMAND_END = 3

Used in: NotificationRequest

repeated PromptMonitorMode modes = 1

Used in: Notification

optional string session = 1
oneof event
- PromptNotificationPrompt prompt = 2
- PromptNotificationCommandStart command_start = 3
- PromptNotificationCommandEnd command_end = 4
optional string unique_prompt_id = 5

Used in: PromptNotification

optional int32 status = 1

Used in: PromptNotification

optional string command = 1

Used in: PromptNotification

optional string placeholder = 1
optional GetPromptResponse prompt = 2

Used in: CellStyle

optional uint32 red = 1
optional uint32 green = 2
optional uint32 blue = 3

Describes an RPC from iTerm2 to script. I don't want to invent my own type system so this is dynamically typed, which matches Python well enough.

Used in: NotificationRequest

optional string name = 1
repeated RPCRegistrationRequest.RPCArgumentSignature arguments = 2
repeated RPCRegistrationRequest.RPCArgument defaults = 4
optional float timeout = 3
If not specified, iTerm2 decides based on its built-in default.
optional RPCRegistrationRequest.Role role = 5
oneof RoleSpecificAttributes
- RPCRegistrationRequest.SessionTitleAttributes session_title_attributes = 7
- RPCRegistrationRequest.StatusBarComponentAttributes status_bar_component_attributes = 8
- RPCRegistrationRequest.ContextMenuAttributes context_menu_attributes = 9
optional string display_name = 6

optional string display_name = 1
optional string unique_identifier = 2

optional string name = 1
optional string path = 2

optional string name = 1

GENERIC = 1
SESSION_TITLE = 2
STATUS_BAR_COMPONENT = 3
CONTEXT_MENU = 4

optional string display_name = 1
Used by SESSION_TITLE to control name in Preferences menu
optional string unique_identifier = 6
Identifies this title provider uniquely. Must not conflict with other title providers. Use a backwards domain name identifying yourself and the feature, like "com.example.featurename"

optional string short_description = 1
Used by STATUS_BAR_COMPONENT
optional string detailed_description = 2
repeated StatusBarComponentAttributes.Knob knobs = 3
optional string exemplar = 4
optional float update_cadence = 5
optional string unique_identifier = 6
Identifies this component uniquely. Must not conflict with other components. Use a backwards domain name identifying yourself and the feature, like "com.example.featurename"
repeated StatusBarComponentAttributes.Icon icons = 7
optional StatusBarComponentAttributes.Format format = 8

Used in: StatusBarComponentAttributes

PLAIN_TEXT = 0
HTML = 1

Used in: StatusBarComponentAttributes

optional bytes data = 1
optional float scale = 2

Used in: StatusBarComponentAttributes

optional string name = 1
optional Knob.Type type = 2
optional string placeholder = 3
optional string json_default_value = 4
optional string key = 5

Used in: Knob

Checkbox = 1
String = 2
PositiveFloatingPoint = 3
Color = 4

Describes a range of values.

Used in: GetBufferResponse, WindowedCoordRange

optional int64 location = 1
optional int64 length = 2

Registers a toolbelt tool that displays a webview with a URL of your choice.

optional string name = 1
This name is displayed to the user.
optional string identifier = 2
The tool's identifier should be unique. Prefix it with your app bundle. For example: com.example.mytool
optional bool reveal_if_already_registered = 5
The first time a tool is registered iTerm2 automatically adds it to the set of visible tools. To show it on subsequent re-registrations, set this to true. If the toolbelt itself is hidden, it will not be opened.
optional RegisterToolRequest.ToolType tool_type = 3
optional string URL = 4
For web view tools: The URL loaded at startup

Used in: RegisterToolRequest

WEB_VIEW_TOOL = 1

optional RegisterToolResponse.Status status = 1

Used in: RegisterToolResponse

OK = 0
REQUEST_MALFORMED = 1
PERMISSION_DENIED = 2

repeated ReorderTabsRequest.Assignment assignments = 3

Used in: ReorderTabsRequest

optional string window_id = 1
repeated string tab_ids = 2

optional ReorderTabsResponse.Status status = 4

Used in: ReorderTabsResponse

OK = 0
INVALID_ASSIGNMENT = 1
e.g., duplicate tab id
INVALID_WINDOW_ID = 2
INVALID_TAB_ID = 3

optional string session_id = 1
"all" not allowed.
optional bool only_if_exited = 2
If set, then still-running sessions will fail to restart with SESSION_NOT_RESTARTABLE. If not set, then a still-running session gets killed and restarted.

optional RestartSessionResponse.Status status = 1

Used in: RestartSessionResponse

OK = 0
SESSION_NOT_FOUND = 1
SESSION_NOT_RESTARTABLE = 2
Some sessions, such as tmux integration sessions, are not restartable. Also, when `only_if_exited` is set in the request and the session is still running then this status will be returned.

optional string name = 1
Not used for LIST
optional SavedArrangementRequest.Action action = 2
optional string window_id = 3
If given and the action is SAVE then only the tabs in the identified window are saved. If given and the action is RESTORE then the arrangement will be restored as tabs in the identified window. Not used for LIST

Used in: SavedArrangementRequest

RESTORE = 0
Restore an existing arrangement with the given name
SAVE = 1
Save windows to a new arrangement with the given name
LIST = 2
List arrangements

optional SavedArrangementResponse.Status status = 1
repeated string names = 2

Used in: SavedArrangementResponse

OK = 0
ARRANGEMENT_NOT_FOUND = 1
Tried to restore, but name doesn't exist
WINDOW_NOT_FOUND = 2
Bad window ID provided
REQUEST_MALFORMED = 3

Used in: Notification

optional string session = 1

Used in: SelectionRequest.SetSelectionRequest, SelectionResponse.GetSelectionResponse

repeated SubSelection sub_selections = 1

Used in: SubSelection

CHARACTER = 0
WORD = 1
LINE = 2
SMART = 3
BOX = 4
WHOLE_LINE = 5

oneof request
- SelectionRequest.GetSelectionRequest get_selection_request = 1
- SelectionRequest.SetSelectionRequest set_selection_request = 2

Used in: SelectionRequest

optional string session_id = 1

Used in: SelectionRequest

optional string session_id = 1
optional Selection selection = 2

optional SelectionResponse.Status status = 1
oneof response
- SelectionResponse.GetSelectionResponse get_selection_response = 2
- SelectionResponse.SetSelectionResponse set_selection_response = 3

Used in: SelectionResponse

optional Selection selection = 2

Used in: SelectionResponse

(message has no fields)

Used in: SelectionResponse

OK = 0
INVALID_SESSION = 1
INVALID_RANGE = 2
REQUEST_MALFORMED = 3

optional string session = 1
See documentation on session IDs
optional string text = 2
The text to send. As usual for proto buffers, this should be UTF-8 encoded. It will be converted to the session's encoding before being sent.
optional bool suppress_broadcast = 3
If set, input will not be broadcast when broadcasting is on.

optional SendTextResponse.Status status = 1

Used in: SendTextResponse

OK = 0
SESSION_NOT_FOUND = 1

All responses are wrapped in this message. This encoded message is the entirety of the payload of messages sent over WebSocket from iTerm2 to client.

optional int64 id = 1
oneof submessage
Responses to ClientOriginatedMessages of the corresponding type
- string error = 2
  Set if request was malformed
- GetBufferResponse get_buffer_response = 100
- GetPromptResponse get_prompt_response = 101
- TransactionResponse transaction_response = 102
- NotificationResponse notification_response = 103
- RegisterToolResponse register_tool_response = 104
- SetProfilePropertyResponse set_profile_property_response = 105
- ListSessionsResponse list_sessions_response = 106
- SendTextResponse send_text_response = 107
- CreateTabResponse create_tab_response = 108
- SplitPaneResponse split_pane_response = 109
- GetProfilePropertyResponse get_profile_property_response = 110
- SetPropertyResponse set_property_response = 111
- GetPropertyResponse get_property_response = 112
- InjectResponse inject_response = 113
- ActivateResponse activate_response = 114
- VariableResponse variable_response = 115
- SavedArrangementResponse saved_arrangement_response = 116
- FocusResponse focus_response = 117
- ListProfilesResponse list_profiles_response = 118
- ServerOriginatedRPCResultResponse server_originated_rpc_result_response = 119
- RestartSessionResponse restart_session_response = 120
- MenuItemResponse menu_item_response = 121
- SetTabLayoutResponse set_tab_layout_response = 122
- GetBroadcastDomainsResponse get_broadcast_domains_response = 123
- TmuxResponse tmux_response = 124
- ReorderTabsResponse reorder_tabs_response = 125
- PreferencesResponse preferences_response = 126
- ColorPresetResponse color_preset_response = 127
- SelectionResponse selection_response = 128
- StatusBarComponentResponse status_bar_component_response = 129
- SetBroadcastDomainsResponse set_broadcast_domains_response = 130
- CloseResponse close_response = 131
- InvokeFunctionResponse invoke_function_response = 132
- ListPromptsResponse list_prompts_response = 133
- Notification notification = 1000
  This is the only response that is sent spontaneously. The 'id' field will not be set.

Used in: ServerOriginatedRPCNotification

optional string name = 2
repeated ServerOriginatedRPC.RPCArgument arguments = 3

Used in: ServerOriginatedRPC

optional string name = 1
optional string json_value = 2

This is an iTerm2-to-script RPC call. The script must have registered for an RPC matching the signature of `rpc`.

Used in: Notification

optional string request_id = 1
optional ServerOriginatedRPC rpc = 2

This is the result of an iTerm2-to-script RPC call.

optional string request_id = 1
oneof result
- string json_exception = 2
  Exceptions should be dictionaries with a key of "reason" having a string value describing what went wrong.
- string json_value = 3

This simply acknowledges receipt of ServerOriginatedRPCResultRequest.

(message has no fields)

Used in: ListSessionsResponse, ListSessionsResponse.Tab, SplitTreeNode.SplitTreeLink

optional string unique_identifier = 1
optional Frame frame = 2
will not be set for buried sessions
optional Size grid_size = 3
will not be set for buried sessions
optional string title = 4

repeated BroadcastDomain broadcast_domains = 1

optional SetBroadcastDomainsResponse.Status status = 1

Used in: SetBroadcastDomainsResponse

OK = 0
SESSION_NOT_FOUND = 1
BROADCAST_DOMAINS_NOT_DISJOINT = 2
SESSIONS_NOT_IN_SAME_WINDOW = 3

Sets a value in a session's copy of the profile without modifying the underlying profile.

oneof target
- string session = 1
  See documentation on session IDs
- SetProfilePropertyRequest.GuidList guid_list = 2
optional string key = 3
deprecated
optional string json_value = 4
deprecated
repeated SetProfilePropertyRequest.Assignment assignments = 5

Used in: SetProfilePropertyRequest

optional string key = 1
optional string json_value = 2

Used in: SetProfilePropertyRequest

repeated string guids = 1

optional SetProfilePropertyResponse.Status status = 1

Used in: SetProfilePropertyResponse

OK = 0
SESSION_NOT_FOUND = 1
REQUEST_MALFORMED = 2
BAD_GUID = 3

oneof identifier
Eventually you'll be able to set properties on other things besides The kind of ID that's set determines the kind of object you're updating.
- string window_id = 1
- string session_id = 5
  Accepts "all" and "active"
optional string name = 3
For windows: Name Example JSON ------------- --------------- frame { "origin": { "x": 0, "y": 0 }, "size": { "width": 1024, "height": 768 }} fullscreen true, false For sessions: grid_size { "width": 80, "height": 25 } buried true
optional string json_value = 4

optional SetPropertyResponse.Status status = 1

Used in: SetPropertyResponse

OK = 0
UNRECOGNIZED_NAME = 1
INVALID_VALUE = 2
e.g., bad JSON value
INVALID_TARGET = 3
e.g., bogus window_id
DEFERRED = 4
Operation can't be performed immediately. Will be tried later. For example, resizing a session during instant replay.
IMPOSSIBLE = 5
Can't be done. For example, resizing a session in a full-screen window.
FAILED = 6
Did our best and failed. For example, sometimes toggling full-screen fails if another window is also toggling. Maybe try again?

optional SplitTreeNode root = 1
The tree structure must exactly match the actual tree structure, including the `vertical` setting. Only the grid_sizes may change. They must still add up to the same value in every dimension.
optional string tab_id = 2

optional SetTabLayoutResponse.Status status = 1

Used in: SetTabLayoutResponse

OK = 0
BAD_TAB_ID = 1
WRONG_TREE = 2
INVALID_SIZE = 3

Used in: Frame, SessionSummary, StatusBarComponentRequest.OpenPopover

optional int32 width = 1
optional int32 height = 2

optional string session = 1
See documentation on session IDs
optional SplitPaneRequest.SplitDirection split_direction = 2
optional bool before = 3
If true, new session is above/left of the session being split. Otherwise, it goes below/right.
optional string profile_name = 4
Leave unset to use the default profile.
repeated ProfileProperty custom_profile_properties = 5
Modifies the profile to customize its behavior just for this session.

Used in: SplitPaneRequest

VERTICAL = 0
HORIZONTAL = 1

optional SplitPaneResponse.Status status = 1
repeated string session_id = 2
TODO(gln): this will not be set for tmux integration because the split happens only if/when the tmux server acts on the request. See documentation on session IDs. If more than one session was split, there will be multiple session_id's.

Used in: SplitPaneResponse

OK = 0
SESSION_NOT_FOUND = 1
INVALID_PROFILE_NAME = 2
CANNOT_SPLIT = 3
This can happen if the session to be split is too small. If splitting multiple sessions and one or more cannot be split, the status will be set to CANNOT_SPLIT, even if some did succeed (in which case there will be one or more session_id's).
MALFORMED_CUSTOM_PROFILE_PROPERTY = 4
Couldn't decode JSON

Used in: ListSessionsResponse.Tab, SetTabLayoutRequest, SplitTreeNode.SplitTreeLink

optional bool vertical = 1
Direction of split pane divider
repeated SplitTreeNode.SplitTreeLink links = 2
Links to children

Used in: SplitTreeNode

oneof child
- SessionSummary session = 1
- SplitTreeNode node = 2

oneof request
- StatusBarComponentRequest.OpenPopover open_popover = 1
optional string identifier = 2
ID of statusbar component

Used in: StatusBarComponentRequest

optional string session_id = 1
optional string html = 2
HTML to show in a popover that opens from the component.
optional Size size = 3
Size in points of the content area of the popover.

optional StatusBarComponentResponse.Status status = 1

Used in: StatusBarComponentResponse

OK = 0
SESSION_NOT_FOUND = 1
REQUEST_MALFORMED = 2
INVALID_IDENTIFIER = 3

Used in: Selection

optional WindowedCoordRange windowed_coord_range = 1
optional SelectionMode selection_mode = 2
optional bool connected = 3

Used in: Notification

optional string session_id = 1

oneof payload
- TmuxRequest.ListConnections list_connections = 1
- TmuxRequest.SendCommand send_command = 2
- TmuxRequest.SetWindowVisible set_window_visible = 3
- TmuxRequest.CreateWindow create_window = 4

Used in: TmuxRequest

optional string connection_id = 1
optional string affinity = 2

Used in: TmuxRequest

(message has no fields)

Used in: TmuxRequest

optional string connection_id = 1
optional string command = 2

Used in: TmuxRequest

optional string connection_id = 1
optional string window_id = 2
optional bool visible = 3

oneof payload
- TmuxResponse.ListConnections list_connections = 1
- TmuxResponse.SendCommand send_command = 2
- TmuxResponse.SetWindowVisible set_window_visible = 3
- TmuxResponse.CreateWindow create_window = 5
optional TmuxResponse.Status status = 4

Used in: TmuxResponse

optional string tab_id = 1
This is an iTerm2 tab ID.

Used in: TmuxResponse

repeated ListConnections.Connection connections = 1

Used in: ListConnections

optional string connection_id = 1
optional string owning_session_id = 2

Used in: TmuxResponse

optional string output = 1
If not set, an error occurred.

Used in: TmuxResponse

(message has no fields)

Used in: TmuxResponse

OK = 0
INVALID_REQUEST = 1
INVALID_CONNECTION_ID = 2
INVALID_WINDOW_ID = 3

optional bool begin = 1
Set to true to begin a new transaction or false to end the current transaction. The app's main loop will not advance while in a transaction. This effectively freezes time. Keep transactions short.

optional TransactionResponse.Status status = 1

Used in: TransactionResponse

OK = 0
NO_TRANSACTION = 1
ALREADY_IN_TRANSACTION = 2

Used in: CellStyle

optional string url = 1
optional string identifier = 2

Used in: Notification

optional VariableScope scope = 1
optional string identifier = 2
unset if app scope, otherwise is session, window, or tab ID
optional string name = 3
optional string json_new_value = 4
Will be "null" if unset.

Used in: NotificationRequest

optional string name = 1
optional VariableScope scope = 2
optional string identifier = 3
Session, Window, or Tab identifier.

oneof scope
- string session_id = 1
  "all" is allowed only if no gets (only sets allowed)
- string tab_id = 4
  "all" is allowed only if no gets (only sets allowed)
- bool app = 5
- string window_id = 6
  "all" is allowed only if no gets (only sets allowed)
repeated VariableRequest.Set set = 2
repeated string get = 3
Set to special value "*" to get all in a JSON dictionary

Used in: VariableRequest

optional string name = 1
optional string value = 2
JSON encoded