App¶

Provides access to application-level structures.

This module is the starting point for getting access to windows and other application-global data.

async async_get_app(connection: iterm2.connection.Connection, create_if_needed: bool = True) → Union[None, iterm2.app.App]¶

Returns the app singleton, creating it if needed.

Parameters:

connection (Connection) – The connection to iTerm2.
create_if_needed (bool) – If True, create the global App instance if one does not already exists. If False, do not create it.

Returns:

The global App instance. If create_if_needed is False this may return None if no such instance exists.

async async_invoke_function(connection: iterm2.connection.Connection, invocation: str, timeout: float = - 1)¶

Invoke an RPC. Could be a registered function by this or another script of a built-in function.

This invokes the RPC in the global application context. Note that most user-defined RPCs expect to be invoked in the context of a session. Default variables will be pulled from that scope. If you call a function from the wrong context it may fail because its defaults will not be set properly.

Parameters:

invocation (str) – A function invocation string.
timeout (float) – Max number of secondsto wait. Negative values mean to use the system default timeout.

Returns:

The result of the invocation if successful.

Throws:

RPCException if something goes wrong.

class App(connection, windows, buried_sessions)¶

Represents the application.

Stores and provides access to app-global state. Holds a collection of terminal windows and provides utilities for them.

This object keeps itself up to date by getting notifications when sessions, tabs, or windows change.

async async_activate(raise_all_windows: bool = True, ignoring_other_apps: bool = False) → None ¶

Activate the app, giving it keyboard focus.

Parameters:

raise_all_windows (bool) – Raise all windows if True, or only the key window. Defaults to True.
ignoring_other_apps (bool) – If True, activate even if the user interacts with another app after the call.

async async_apply_layout(spec: Dict[str, Any])¶

Apply a target layout to one or more tabs.

Supports reshaping existing tabs (including swapping panes and rearranging the split tree) and moving sessions across tabs and windows.

Validation runs in two phases: a structural pre-check before any mutation (rejects malformed specs without side effects), then per-tab mutations. If a per-tab mutation fails partway through the plan, the transaction aborts and the error propagates to the caller; the parts already mutated remain mutated (there is no rollback). The structural pre-check makes mid-plan failures rare in practice, but callers should not assume the API is all-or-nothing in the face of unexpected errors.

Parameters:

spec –

A dictionary describing the target state. Schema:

{
    "tabs": [
        {"tab_id": "<guid>", "root": <node>},  # reshape
    ],
    "close_sessions": ["<guid>", ...],     # explicit closes
    "close_tabs":     ["<guid>", ...],
    "close_windows":  ["<guid>", ...],
}

A <node> is one of:

{"session_id": "<guid>"} — leaf referring to a live session.
{"new_session": {"profile": "<profile-guid>", "command": "<optional>"}} — leaf that creates a brand-new session with the named profile (and optional command override) in place. If given, command runs in a login shell (your PATH, aliases, and dotfiles are sourced), as if you had typed it. The new pane is sized to its even share of its container; you cannot specify a size. It honors the profile’s working-directory setting: Home and Custom Directory behave as configured, and “Reuse previous session’s directory” inherits from an existing pane in the destination tab (so it lands where a hand-made split would). Requires iTerm2 new enough to advertise the capability (see iterm2.capabilities.supports_apply_layout_new_session()).
{"vertical": True, "children": [<node>, <node>, ...]} — splitter with at least 2 children.

Validation rules enforced server-side:

Splitters must have at least 2 children.
Same-orientation nesting (V inside V, H inside H) is rejected — flatten yourself.
Every session GUID that appears in the spec may appear at most once.
Every tab affected by a session move must be listed in tabs (or its sessions accounted for via close_sessions / close_tabs).
Every new_session profile GUID must name a real profile.
tmux integration tabs are not supported.

Limitations: new_session leaves create sessions in existing tabs only. The new_tabs and new_windows fields are not supported; use async_create_tab() / async_create() to make new tabs and windows, then reshape them with apply_layout.

Throws:

RPCException on validation failure or execution error. The error message includes a tree-path indicating the offending node.

Example: replace a tab’s single session with a 3-pane layout, keeping the existing session on the left and creating two new ones on the right, in one call.

session = tab.sessions[0]
profile = await session.async_get_profile()
guid = profile.guid
spec = {
    "tabs": [
        {
            "tab_id": tab.tab_id,
            "root": {
                "vertical": True,  # left | right
                "children": [
                    {"session_id": session.session_id},
                    {
                        "vertical": False,  # top / bottom
                        "children": [
                            {"new_session": {"profile": guid,
                                             "command": "htop"}},
                            {"new_session": {"profile": guid}},
                        ],
                    },
                ],
            },
        },
    ],
}
await app.async_apply_layout(spec)

async async_get_theme() → List[str]¶

Gets attributes the current theme.

The automatic and minimal themes will always include “dark” or “light”.

On macOS 10.14, the light or dark attribute may be inferred from the system setting.

Returns:: A list of one or more strings from the set: light, dark, automatic, minimal, highContrast.

async async_get_variable(name: str) → Any¶

Fetches the value of a variable from the global context.

See Scripting Fundamentals for details on variables.

Parameters:: name (str) – The variable’s name.
Returns:: The variable’s value or empty string if it is undefined.
Throws:: RPCException if something goes wrong.

async async_move_session(session: iterm2.session.Session, destination: iterm2.session.Session, split_vertically: bool, before: bool)¶

Move a session to be a split pane by splitting another existing session.

Parameters:

split_vertically (bool) – If True, split the destination session vertically.
before (bool) – If True, place session left of/above destionation.

async async_set_variable(name: str, value: Any) → None ¶

Sets a user-defined variable in the application.

See the Scripting Fundamentals documentation for more information on user-defined variables.

Parameters:

name (str) – The variable’s name. Must begin with user..
value – The new value to assign.

Throws:

RPCException if something goes wrong.

property broadcast_domains: List[iterm2.broadcast.BroadcastDomain]¶

Returns the current broadcast domains.

App¶

Indices and tables¶