List all iTerm2 windows, tabs, and sessions.

Returns a tree with session IDs that can be passed to other tools. The * marker shows the currently focused window, tab, and session.

Return the ID and name of the currently focused iTerm2 session.

Bring a session to the foreground.

:param session_id: The session UUID to activate. Its window is raised and its tab/pane is selected.

Send text to an iTerm2 session.

:param text: The characters to send. :param session_id: Target session UUID. Defaults to the active session. :param add_newline: If True (the default), appends \n so commands execute. Set to False to type without submitting, e.g. when filling an interactive prompt.

Send a control character to an iTerm2 session.

Supported values: any single letter A-Z (Ctrl-A through Ctrl-Z), ESC/ESCAPE for Escape (0x1B), and ] for the telnet escape (0x1D).

:param letter: The control key name; see above for accepted forms. :param session_id: Target session UUID. Defaults to the active session.

Send a raw escape sequence to an iTerm2 session.

Python string escapes in sequence are interpreted before sending, so values like \x1b[2J (clear screen) or \x1b[H (cursor home) work as expected.

:param sequence: The escape sequence string. :param session_id: Target session UUID. Defaults to the active session.

Read the visible contents of an iTerm2 session as plain text.

ANSI escape codes are stripped. Trailing blank lines are trimmed.

:param session_id: Target session UUID. Defaults to the active session. :param max_lines: If set, return only the last N lines.

Return the cursor coordinates x, y within the visible screen.

:param session_id: Target session UUID. Defaults to the active session.

Run a command and wait for it to finish, returning the resulting screen.

Completion is detected via iTerm2's PromptMonitor COMMAND_END notification, which requires iTerm2 shell integration to be installed in the target shell. If the prompt-end event does not arrive within timeout_seconds, the current screen is returned with a [timeout] marker.

:param command: The command line to run. :param session_id: Target session UUID. Defaults to the active session. :param timeout_seconds: How long to wait for COMMAND_END before giving up.

Create a new iTerm2 window.

:param command: Optional shell command to run in the new session. :param profile: Name of the iTerm2 profile to use. Defaults to the default profile.

Create a new tab in a window.

:param window_id: Target window ID. Defaults to the current window. :param command: Optional shell command to run in the new tab's session. :param profile: Name of the iTerm2 profile to use.

Split an iTerm2 pane horizontally or vertically.

:param session_id: Session UUID to split. Defaults to the active session. :param vertical: If True, split left/right; if False, split top/bottom. :param profile: Name of the iTerm2 profile to use for the new pane. :param command: Optional command to run in the new pane after the split.

Close a specific session.

:param session_id: The session UUID to close. :param force: If True, skip iTerm2's "running process" confirmation prompt.

Set the title/name of an iTerm2 session.

:param name: The new session name. :param session_id: Target session UUID. Defaults to the active session.

Set the iTerm2 session badge (translucent overlay text).

The profile's Badge field must reference \(user.badge) for the value to show up; this is the default in stock profiles.

:param badge: Text to display as the badge. :param session_id: Target session UUID. Defaults to the active session.

Clear both the visible screen and the scrollback buffer.

Uses the iTerm2-proprietary OSC 1337 ; ClearScrollback control sequence (https://iterm2.com/documentation-escape-codes.html).

:param session_id: Target session UUID. Defaults to the active session.

List all iTerm2 profiles with their names and GUIDs.

Read an iTerm2 session variable.

Commonly useful names: jobName, jobPid, path (requires shell integration), username, hostname, rows, columns, autoName. Prefix with user. for variables set via iTerm2 custom control sequences.

:param name: The variable name to read. :param session_id: Target session UUID. Defaults to the active session.