iTerm2 Python API

https://iterm2.com/python-api
Admin
iTerm2 Python API is a Python package that enables developers to write scripts to control iTerm2 and...
Tokens:210,012
Snippets:2,090
Trust Score:9.7
Update:6 hours ago
Show doc for...
Tokens:
Raw
### Full example script

Source: https://iterm2.com/python-api/tutorial/example.html

The complete example script provided by iTerm2, minus some comments. It imports iterm2, defines an async main function that gets the app, creates a tab in the current window if one exists, and runs the script.

```python
#!/usr/bin/env python3

import iterm2

async def main(connection):
    app = await iterm2.async_get_app(connection)
    window = app.current_window
    if window is not None:
        await window.async_create_tab()
    else:
        print("No current window")

iterm2.run_until_complete(main)
```

--------------------------------

### Create a task for each session with EachSessionOnceMonitor

Source: https://iterm2.com/python-api/lifecycle.html

This example gets the app instance, defines a coroutine that monitors prompts in a session, and uses EachSessionOnceMonitor.async_foreach_session_create_task to run it for each session. The coroutine prints 'Prompt detected' when a prompt is detected.

```python
app = await iterm2.async_get_app(connection)
# Print a message to stdout when there's a new prompt in any
# session
async def my_task(session_id):
    async with iterm2.PromptMonitor(connection, session_id) as mon:
        await mon.async_get()
        print("Prompt detected")

await (iterm2.EachSessionOnceMonitor.
    async_foreach_session_create_task(app, my_task))
```

--------------------------------

### REPL session: create connection and get app

Source: https://iterm2.com/python-api/tutorial/running.html

Use this in the iTerm2 Python REPL (Scripts > Open Python REPL) to start interacting with the API. The REPL supports await directly, so you don't need to wrap code in iterm2.run_until_complete(main). The REPL prints this sample script at startup for copy-paste.

```python
import iterm2
connection=await iterm2.Connection.async_create()
app=await iterm2.async_get_app(connection)
```

--------------------------------

### Example: replace a tab's single session with a 3-pane layout

Source: https://iterm2.com/python-api/app.html

This example shows how to use async_apply_layout to 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. It uses the session's profile GUID and the 'new_session' node type.

```python
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)
```

--------------------------------

### Apply Layout Example Script

Source: https://iterm2.com/python-api/examples/apply_layout.html

Complete example script that registers three RPCs to move sessions between tabs, windows, and split panes using App.async_apply_layout. Bind any of these to a keystroke in Prefs > Keys via 'Invoke Script Function'.

```python
#!/usr/bin/env python3.7
"""
Demo: move sessions between tabs, windows, and split panes via
App.async_apply_layout.

Registers three RPCs:
  swap_first_two_panes()
  move_active_pane_to_next_tab()
  move_active_pane_to_other_window()

Bind any of these to a keystroke in Prefs > Keys via "Invoke Script
Function".
"""

import iterm2

def leaf(session):
    """Build a leaf node for a session."""
    return {"session_id": session.session_id}

def vrow(sessions):
    """Build a vertical-divider row of one or more sessions.

    A single session is returned as a leaf; two or more become a
    splitter. apply_layout requires splitters to have at least two
    children.
    """
    if len(sessions) == 1:
        return leaf(sessions[0])
    return {"vertical": True,
            "children": [leaf(s) for s in sessions]}

async def main(connection):
    app = await iterm2.async_get_app(connection)

    @iterm2.RPC
    async def swap_first_two_panes():
        """Swap the first two panes of the current tab."""
        tab = app.current_terminal_window.current_tab
        if len(tab.sessions) < 2:
            return
        a, b = tab.sessions[0], tab.sessions[1]
        spec = {
            "tabs": [{
                "tab_id": tab.tab_id,
                "root": {
                    "vertical": True,
                    "children": [leaf(b), leaf(a)] +
                                [leaf(s) for s in tab.sessions[2:]],
                },
            }],
        }
        await app.async_apply_layout(spec)
    await swap_first_two_panes.async_register(connection)

    @iterm2.RPC
    async def move_active_pane_to_next_tab():
        """Move the active pane from the current tab into the next
        tab in the same window."""
        window = app.current_terminal_window
        tabs = window.tabs
        if len(tabs) < 2:
            return
        src = window.current_tab
        i = next(idx for idx, t in enumerate(tabs)
                 if t.tab_id == src.tab_id)
        dst = tabs[(i + 1) % len(tabs)]
        active = src.current_session
        if active is None:
            return

        remaining = [s for s in src.sessions
                     if s.session_id != active.session_id]
        spec = {"tabs": []}
        if remaining:
            # Source tab keeps the other panes.
            spec["tabs"].append(
                {"tab_id": src.tab_id, "root": vrow(remaining)})
        # Destination tab gains the moved pane on the right.
        spec["tabs"].append({
            "tab_id": dst.tab_id,
            "root": vrow(list(dst.sessions) + [active]),
        })
        # If the source tab loses every pane, apply_layout will
        # close it for us automatically — no need to list it in
        # close_tabs.
        await app.async_apply_layout(spec)
    await move_active_pane_to_next_tab.async_register(connection)

    @iterm2.RPC
    async def move_active_pane_to_other_window():
        """Move the active pane to the current tab of another
        window. Picks the next window in app.terminal_windows."""
        windows = app.terminal_windows
        if len(windows) < 2:
            return
        src_window = app.current_terminal_window
        i = next(idx for idx, w in enumerate(windows)
                 if w.window_id == src_window.window_id)
        dst_window = windows[(i + 1) % len(windows)]
        src_tab = src_window.current_tab
        dst_tab = dst_window.current_tab
        active = src_tab.current_session
        if active is None:
            return

        remaining = [s for s in src_tab.sessions
                     if s.session_id != active.session_id]
        spec = {"tabs": []}
        if remaining:
            spec["tabs"].append(
                {"tab_id": src_tab.tab_id, "root": vrow(remaining)})
        spec["tabs"].append({
            "tab_id": dst_tab.tab_id,
            "root": vrow(list(dst_tab.sessions) + [active]),
        })
        await app.async_apply_layout(spec)
    await move_active_pane_to_other_window.async_register(connection)

iterm2.run_forever(main)

```

--------------------------------

### Install dependencies for launching iTerm2 from command line

Source: https://iterm2.com/python-api/examples/launch_and_run.html

Install Python, the iterm2 package, and pyobjc using Homebrew and pip. Required to run the script from the command line.

```bash
brew install python3
pip3 install iterm2
pip3 install pyobjc
```

--------------------------------

### Profile.async_get(connection, guids=None)

Source: https://iterm2.com/python-api/profile.html

Fetches all profiles with the specified GUIDs. If guids is None, all profiles are returned.

```APIDOC
## Profile.async_get(connection, guids=None)

### Description
Fetches all profiles with the specified GUIDs. If guids is None, all profiles are returned.

### Parameters
- **guids** – The profiles to get, or if None then all will be returned.

### Returns
A list of `Profile` objects.
```

--------------------------------

### Profile.async_set_use_cursor_guide

Source: https://iterm2.com/python-api/genindex.html

Asynchronously sets whether to use the cursor guide for the profile.

```APIDOC
## Profile.async_set_use_cursor_guide

### Description
Asynchronously sets whether to use the cursor guide for the profile.

### Method
async

### Signature
`async_set_use_cursor_guide(value)`

### Parameters
- **value** (bool) - Required - The new value for the use_cursor_guide setting.

### Returns
None
```

--------------------------------

### Profile.command

Source: https://iterm2.com/python-api/profile.html

Returns the command to run when the session starts.

```APIDOC
## Profile.command

### Description
Returns the command to run when the session starts. The value is a string giving the command to run.

### Returns
A str
```

--------------------------------

### Profile.async_set_cursor_guide_color()

Source: https://iterm2.com/python-api/genindex.html

Sets the cursor guide color for a Profile.

```APIDOC
## Profile.async_set_cursor_guide_color()

### Description
Sets the cursor guide color for a Profile.

### Method
async_set_cursor_guide_color()

### Class
Profile

### Module
iterm2
```

--------------------------------

### Install aiohttp dependency

Source: https://iterm2.com/python-api/examples/targeted_input.html

Command to install the aiohttp package for the TargetedInput script. Run after creating the script as a Full Environment script, adjusting the path if the script name differs.

```bash
~/Library/ApplicationSupport/iTerm2/Scripts/TargetedInput/iterm2env/versions/*/bin/pip3 install aiohttp
```

--------------------------------

### async_set_use_cursor_guide(value: bool)

Source: https://iterm2.com/python-api/profile.html

Sets whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

```APIDOC
## async_set_use_cursor_guide(value: bool)

### Description
Sets whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

### Method
async

### Parameters
- **value** (bool) - Required - A bool.

```

--------------------------------

### Profile.use_cursor_guide

Source: https://iterm2.com/python-api/profile.html

Returns whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

```APIDOC
## Profile.use_cursor_guide

### Description
Returns whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

### Returns
A bool
```

--------------------------------

### PartialProfile.async_get_full_profile

Source: https://iterm2.com/python-api/profile.html

Requests a full profile and returns it. Raises BadGUIDException if the Guid is not set or does not match a profile.

```APIDOC
## async_get_full_profile() -> Profile

### Description
Requests a full profile and returns it.

Raises BadGUIDException if the Guid is not set or does not match a profile.

### Returns
A Profile.

```

--------------------------------

### list_profiles(connection, properties, guids)

Source: https://iterm2.com/python-api/profile.html

Fetches a list of PartialProfile objects with specified properties. Pass None for properties to fetch all, and None for guids to list all profiles.

```APIDOC
## list_profiles(connection, properties, guids)

### Description
Fetches a list of PartialProfile objects with only the specified properties set. Pass None for properties to fetch all, and None for guids to list all profiles.

### Parameters
- **connection** (Connection) - Required - The connection to send the query to.
- **properties** - Required - Lists the properties to fetch. Pass None for all. If you wish to fetch the full profile later, you must ensure the 'Guid' property is fetched.
- **guids** - Required - Lists GUIDs to list. Pass None for all profiles.

### Returns
A list of PartialProfile objects with only the specified properties set.
```

--------------------------------

### Prompt

Source: https://iterm2.com/python-api/prompt.html

Describes a command prompt. Do not construct this object yourself; use async_get_last_prompt() to get an instance.

```APIDOC
## Prompt

### Description
Describes a command prompt. Shell Integration must be installed for this to work properly. Do not construct this object yourself. Use `async_get_last_prompt()` to get an instance.

### Properties
- **command** (None | str) - Returns the command entered at the prompt.
- **command_range** (CoordRange) - Gives the CoordRange of the command following the shell prompt.
- **output_range** (CoordRange) - Gives the CoordRange of the output of a command following a shell prompt.
- **prompt_range** (CoordRange) - Gives the CoordRange of a shell prompt.
- **working_directory** (None | str) - Returns the working directory at the time the prompt was printed.
```

--------------------------------

### set_use_cursor_guide

Source: https://iterm2.com/python-api/profile.html

Sets whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

```APIDOC
## set_use_cursor_guide

### Description
Sets whether the cursor guide should be used. This is used only when separate light/dark mode colors are not enabled.

### Method
set_use_cursor_guide

### Parameters
- **value** (bool) - Required - A bool

```

--------------------------------

### RPC invocation syntax example

Source: https://iterm2.com/python-api/tutorial/rpcs.html

Shows the language-agnostic syntax used when iTerm2 invokes a registered RPC. Arguments use identifiers, variable references, numbers, and strings. Identifiers must be ASCII and each argument name must be distinct.

```text
my_function_name(session: id, favorite_number: 123, nickname: "Joe")
```

--------------------------------

### App.async_activate(raise_all_windows=True, ignoring_other_apps=False)

Source: https://iterm2.com/python-api/app.html

Activate the app, giving it keyboard focus.

```APIDOC
## App.async_activate(raise_all_windows=True, ignoring_other_apps=False)

### Description
Activate the app, giving it keyboard focus.

### Method
async function

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

--------------------------------

### RPC decorator example: split_current_session_n_times

Source: https://iterm2.com/python-api/registration.html

Shows how to use the @iterm2.RPC decorator to register a coroutine as an RPC. The coroutine uses iterm2.Reference("id") to get the session ID and must call async_register(connection) to complete registration.

```python
app = await iterm2.async_get_app(connection)

@iterm2.RPC
async def split_current_session_n_times(
        session_id=iterm2.Reference("id"), n=1):
    session = app.get_session_by_id(session_id)
    for i in range(n):
        await session.async_split_pane()

# Remember to call async_register!
await split_current_session_n_times.async_register(connection)
```

--------------------------------

### Launch iTerm2 and run a command with iterm2.Window.async_create

Source: https://iterm2.com/python-api/examples/launch_and_run.html

Launches iTerm2 using AppKit, then creates a window that runs 'vi' via bash. The script uses iterm2.run_until_complete with True to keep trying to connect until the app launches.

```python
#!/usr/bin/env python3

import iterm2
import AppKit

# Launch the app
AppKit.NSWorkspace.sharedWorkspace().launchApplication_("iTerm2")

async def main(connection):
    app = await iterm2.async_get_app(connection)

    # Foreground the app
    await app.async_activate()

    # This will run 'vi' from bash. If you use a different shell, you'll need
    # to change it here. Running it through the shell sets up your $PATH so you
    # don't need to specify a full path to the command.
    await iterm2.Window.async_create(connection, command="/bin/bash -l -c vi")

# Passing True for the second parameter means keep trying to
# connect until the app launches.
iterm2.run_until_complete(main, True)
```

--------------------------------

### Window.async_create(connection, profile=None, command=None, profile_customizations=None)

Source: https://iterm2.com/python-api/window.html

Creates a new window. This is a static method. Returns a new Window or None if the session ended right away.

```APIDOC
## Window.async_create(connection, profile=None, command=None, profile_customizations=None)

### Description
Creates a new window. This is a static method. Returns a new Window or None if the session ended right away.

### Method
async static

### Signature
`async_create(connection: Connection, profile: str | None = None, command: str | None = None, profile_customizations: None | LocalWriteOnlyProfile = None) -> Window | None`

### Parameters
- **connection** (Connection) - Required - A Connection.
- **profile** (str) - Optional - The name of the profile to use for the new window.
- **command** (str) - Optional - A command to run in lieu of the shell in the new session. Mutually exclusive with profile_customizations.
- **profile_customizations** (LocalWriteOnlyProfile) - Optional - LocalWriteOnlyProfile giving changes to make in profile. Mutually exclusive with command.

### Returns
A new Window or None if the session ended right away.

### Throws
CreateWindowException if something went wrong.
```

--------------------------------

### async_get_app(connection, create_if_needed=True)

Source: https://iterm2.com/python-api/app.html

Returns the app singleton, creating it if needed. This is the entry point for accessing application-level structures.

```APIDOC
## async_get_app(connection, create_if_needed=True)

### Description
Returns the app singleton, creating it if needed.

### Method
async function

### Parameters
- **connection** (Connection) - Required - The connection to iTerm2.
- **create_if_needed** (bool) - Optional - If True, create the global App instance if one does not already exist. 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.
```

--------------------------------

### Run a command and return its output

Source: https://iterm2.com/python-api/examples/runcommand.html

This script runs a command in the current terminal session and prints its output. It requires shell integration. The script uses iterm2.Transaction to atomically get the last prompt, send the command, and start watching for the command end. It then fetches the output range and returns the content.

```python
#!/usr/bin/env python3

import asyncio
import iterm2

async def wait_for_prompt(connection, my_session):
    """Block until the running command terminates."""
    modes = [iterm2.PromptMonitor.Mode.COMMAND_END]
    async with iterm2.PromptMonitor(connection, my_session.session_id, modes) as prompt_monitor:
        while True:
            type, value = await prompt_monitor.async_get()
            if type == iterm2.PromptMonitor.Mode.COMMAND_END:
                return

async def string_in_lines(my_session, start_y, end_y):
    """Returns a string with the content in a range of lines."""
    contents = await my_session.async_get_contents(start_y, end_y - start_y)
    result = ""
    for line in contents:
        result += line.string
        if line.hard_eol:
            result += "\n"
    return result

async def run_command(connection, my_session, command):
    """Run a command and return its output. Requires shell integration."""
    # Atomically get the last prompt, send a command, and begin watching for the end of the command.
    async with iterm2.Transaction(connection):
        prompt = await iterm2.async_get_last_prompt(connection, my_session.session_id)
        await my_session.async_send_text(command + "\r")
        task = asyncio.create_task(wait_for_prompt(connection, my_session))

    # Wait for the command to end.
    await task

    # Re-fetch the prompt for the command we sent to get the current output range.
    async with iterm2.Transaction(connection):
        prompt = await iterm2.async_get_prompt_by_id(connection, my_session.session_id, prompt.unique_id)
        range = prompt.output_range
        start_y = range.start.y
        end_y = range.end.y

        # Fetch the content in that range and return it
        content = await string_in_lines(my_session, start_y, end_y)
    return content

async def main(connection):
    """Demonstrate how to use run_command"""
    app = await iterm2.async_get_app(connection)
    if app.current_terminal_window:
        my_session = app.current_terminal_window.current_tab.current_session
        print(await run_command(connection, my_session, "seq 150"))

iterm2.run_until_complete(main)
```

--------------------------------

### Window.async_create_tab(profile=None, command=None, index=None, profile_customizations=None, select=True)

Source: https://iterm2.com/python-api/window.html

Creates a new tab in this window. Returns a Tab or None.

```APIDOC
## Window.async_create_tab(profile=None, command=None, index=None, profile_customizations=None, select=True)

### Description
Creates a new tab in this window. Returns a Tab or None.

### Method
async

### Signature
`async_create_tab(profile: str | None = None, command: str | None = None, index: int | None = None, profile_customizations: None | LocalWriteOnlyProfile = None, select: bool = True) -> Tab | None`

### Parameters
- **profile** (str) - Optional - The profile name to use or None for the default profile.
- **command** (str) - Optional - A command to run in lieu of the shell in the new session.
- **index** (int) - Optional - The index at which to insert the new tab.
- **profile_customizations** (LocalWriteOnlyProfile) - Optional - LocalWriteOnlyProfile giving changes to make in profile.
- **select** (bool) - Optional - Whether to select the new tab.

### Returns
A new Tab or None if the session ended right away.

### Throws
Not documented.
```

--------------------------------

### Get the app object

Source: https://iterm2.com/python-api/tutorial/example.html

Gets a reference to the iterm2.App object using await. Must be called with await; forgetting it produces a warning in the Script Console.

```python
app = await iterm2.async_get_app(connection)
```

--------------------------------

### Install pyobjc with pip3

Source: https://iterm2.com/python-api/tutorial/running.html

Install the pyobjc module using the Homebrew-installed pip3 to enable launching iTerm2 from a script. This is required if you want your script to launch iTerm2.

```bash
pip3 install pyobjc
```

--------------------------------

### Window.async_activate()

Source: https://iterm2.com/python-api/window.html

Gives the window keyboard focus and orders it to the front. Note that this won't activate the app; use App.async_activate() as well.

```APIDOC
## Window.async_activate()

### Description
Gives the window keyboard focus and orders it to the front. Note that this won't activate the app; use the `async_activate()` method on `App` to activate the app. You'll probably want to call both methods.

### Method
async

### Signature
`async_activate() -> None`

### Parameters
None

### Returns
None

### Throws
None documented.
```

--------------------------------

### SubSelection.async_get_string

Source: https://iterm2.com/python-api/selection.html

Gets the text belonging to this subselection.

```APIDOC
## SubSelection.async_get_string

### Description
Gets the text belonging to this subselection.

### Method
async method

### Signature
`async async_get_string(connection: Connection, session_id: str) -> str`

### Parameters
- **connection** (Connection) - The connection to iTerm2.
- **session_id** (str) - The ID of the session for which to look up the selected text.

### Returns
- **str** - The text belonging to this subselection.
```

--------------------------------

### CoordRange.start

Source: https://iterm2.com/python-api/util.html

Returns the start Point of the range.

```APIDOC
## CoordRange.start

### Description
Returns the start Point of the range.

### Returns
- **Point** - The start Point.
```

--------------------------------

### async async_activate(select_tab=True, order_window_front=True)

Source: https://iterm2.com/python-api/session.html

Makes the session the active session in its tab, optionally selecting the tab and bringing the window to front.

```APIDOC
## async async_activate(select_tab=True, order_window_front=True)

### Description
Makes the session the active session in its tab.

### Method
Async method

### Parameters
- **select_tab** (bool) - Optional - Whether the tab this session is in should be selected. Default: True.
- **order_window_front** (bool) - Optional - Whether the window this session is in should be brought to the front and given keyboard focus. Default: True.

### Returns
None
```

--------------------------------

### Profile.async_set_initial_directory_mode()

Source: https://iterm2.com/python-api/genindex.html

Sets the initial directory mode of a profile asynchronously.

```APIDOC
## Profile.async_set_initial_directory_mode()

### Description
Sets the initial directory mode of a profile asynchronously.

### Method
async_set_initial_directory_mode

### Class
Profile

### Module
iterm2

### Reference
[iterm2.Profile.async_set_initial_directory_mode](https://iterm2.com/python-api/profile.html#iterm2.Profile.async_set_initial_directory_mode)
```

--------------------------------

### LocalWriteOnlyProfile.set_use_cursor_guide()

Source: https://iterm2.com/python-api/genindex.html

Sets whether to use cursor guide for a profile.

```APIDOC
## LocalWriteOnlyProfile.set_use_cursor_guide()

### Description
Sets whether to use cursor guide for a profile.

### Method
set_use_cursor_guide()

### Parameters
None documented.

### Returns
None documented.
```

--------------------------------

### async_get_tmux_connections() (module iterm2)

Source: https://iterm2.com/python-api/genindex.html

Module-level function to get all tmux connections.

```APIDOC
## async_get_tmux_connections()

### Description
Retrieves all tmux connections.

### Method
Function

### Module
iterm2

### Parameters
- None

### Returns
- **list** - A list of TmuxConnection objects.

```

--------------------------------

### async_get_prompt_by_id() (module iterm2)

Source: https://iterm2.com/python-api/genindex.html

Module-level function to get a prompt by its ID.

```APIDOC
## async_get_prompt_by_id()

### Description
Retrieves a prompt by its unique identifier.

### Method
Function

### Module
iterm2

### Parameters
- **prompt_id** (str) - Required - The ID of the prompt to retrieve.

### Returns
- **Prompt** - The prompt object.

```

--------------------------------

### Profile.automatic_profile_switching_rules

Source: https://iterm2.com/python-api/genindex.html

Property that gets or sets the automatic profile switching rules for the profile.

```APIDOC
## Profile.automatic_profile_switching_rules

### Description
Property that gets or sets the automatic profile switching rules for the profile.

### Type
Property

### Returns
str - The automatic profile switching rules.
```

--------------------------------

### Profile.async_set_advanced_working_directory_window_setting()

Source: https://iterm2.com/python-api/genindex.html

Sets the advanced working directory window setting for a profile.

```APIDOC
## Profile.async_set_advanced_working_directory_window_setting()

### Description
Sets the advanced working directory window setting for a profile.

### Method
async_set_advanced_working_directory_window_setting()

### Parameters
No parameters documented in the source.

### Returns
No return value documented in the source.
```

--------------------------------

### Keycode.HELP

Source: https://iterm2.com/python-api/genindex.html

Keycode constant for the HELP key.

```APIDOC
## Keycode.HELP

### Description
Keycode constant for the HELP key.

### Type
Attribute (int)
```

--------------------------------

### Range(location, length)

Source: https://iterm2.com/python-api/util.html

Describes a range of integers with a starting location and length.

```APIDOC
## Range(location, length)

### Description
Describes a range of integers.

### Parameters
- **location** (int) - Required - The first value in the range.
- **length** (int) - Required - The number of values in the range.
```

--------------------------------

### Python script to open a URL in a browser tab

Source: https://iterm2.com/python-api/examples/open_browser_tab.html

Creates a new tab with a browser profile by setting the Custom Command to 'Browser' via LocalWriteOnlyProfile, then loads a URL using async_load_url(). Requires a URL argument or defaults to https://example.com/. The first time a domain is loaded, iTerm2 prompts for approval; once approved, it is remembered globally.

```python
#!/usr/bin/env python3
import sys
import iterm2


async def main(connection):
    url = sys.argv[1] if len(sys.argv) > 1 else "https://example.com/"

    app = await iterm2.async_get_app(connection)
    window = app.current_terminal_window
    if window is None:
        window = await iterm2.Window.async_create(connection)

    customizations = iterm2.LocalWriteOnlyProfile()
    customizations.set_use_custom_command("Browser")

    tab = await window.async_create_tab(profile_customizations=customizations)
    if tab is None or tab.current_session is None:
        print("Failed to create browser tab.", file=sys.stderr)
        return

    await tab.current_session.async_load_url(url)


iterm2.run_until_complete(main)
```

--------------------------------

### George's Title Algorithm Python script

Source: https://iterm2.com/python-api/examples/georges_title.html

Install this script in ~/Library/Application Support/iTerm2/Scripts/AutoLaunch. It registers a TitleProviderRPC that builds a custom title from user variables and session info. After installation, restart iTerm2 or launch from Scripts > AutoLaunch, then select 'George's Title Algorithm' in Prefs > Profiles > General > Title.

```python
#!/usr/bin/env python3

import asyncio
import iterm2
import os
import subprocess
import sys

def hostname_dash_f():
    process = subprocess.Popen(["hostname", "-f"], stdout=subprocess.PIPE)
    (output, err) = process.communicate()
    exit_code = process.wait()
    return output.decode('utf-8').rstrip()

def shortened_hostname(h):
    i = h.find(".")
    if i < 0:
        return h
    else:
        return h[:i]

def make_title(auto_name, profile_name):
    if auto_name != profile_name:
        return auto_name
    else:
        return ""

def make_hostname(hostname, localhost):
    if not hostname:
        return ""
    short_hostname = shortened_hostname(hostname)
    if short_hostname and short_hostname != localhost:
        return "➥ " + short_hostname
    return ""

def make_pwd(user_home, localhome, pwd):
    if pwd:
        if user_home:
            home = user_home
        else:
            home = localhome
        home_prefix = "📂 "
        if pwd == home:
            home_prefix = ""
            pwd = "🏡"
        elif pwd.startswith(home):
            pwd = "~" + pwd[len(home):]
        if pwd:
            return home_prefix + pwd
    return ""

def make_branch(branch):
    if branch:
        return " ⎇ " + branch.rstrip()
    return ""

async def main(connection):
    localhome = os.environ.get("HOME")
    localhost = hostname_dash_f()

    @iterm2.TitleProviderRPC
    async def georges_title(
        pwd=iterm2.Reference("path?"),
        hostname=iterm2.Reference("hostname?"),
        branch=iterm2.Reference("user.gitBranch?"),
        auto_name=iterm2.Reference("autoName?"),
        profile_name=iterm2.Reference("profileName?"),
        tmux_title=iterm2.Reference("tmuxWindowTitle?"),
        user_home=iterm2.Reference("user.home?")):
        if tmux_title:
            return tmux_title

        parts = [make_title(auto_name, profile_name),
                 make_hostname(hostname, localhost),
                 make_pwd(user_home, localhome, pwd),
                 make_branch(branch)]
        return " ".join(list(filter(lambda x: x, parts)))
    await georges_title.async_register(
            connection,
            display_name="George's Title Algorithm",
            unique_identifier="com.iterm2.example.georges-title-algorithm")

iterm2.run_forever(main)
```

--------------------------------

### async_set_initial_directory_mode

Source: https://iterm2.com/python-api/profile.html

Sets whether to use a custom (not home) initial working directory.

```APIDOC
## async_set_initial_directory_mode

### Description
Sets whether to use a custom (not home) initial working directory.

### Method
async_set_initial_directory_mode

### Parameters
- **value** (InitialWorkingDirectory) - Required - An InitialWorkingDirectory

```

--------------------------------

### set_scrollback_with_status_bar

Source: https://iterm2.com/python-api/profile.html

Sets whether text gets appended to scrollback when there is an app status bar.

```APIDOC
## set_scrollback_with_status_bar(value: bool)

### Description
Sets whether text gets appended to scrollback when there is an app status bar.

### Parameters
- **value** (bool) - Required - A bool

```

--------------------------------

### set_scrollback_in_alternate_screen

Source: https://iterm2.com/python-api/profile.html

Sets whether text gets appended to scrollback in alternate screen mode.

```APIDOC
## set_scrollback_in_alternate_screen(value: bool)

### Description
Sets whether text gets appended to scrollback in alternate screen mode.

### Parameters
- **value** (bool) - Required - A bool

```

--------------------------------

### Window.async_save_window_as_arrangement()

Source: https://iterm2.com/python-api/genindex.html

Saves this window as an arrangement.

```APIDOC
## Window.async_save_window_as_arrangement()

### Description
Saves this window as an arrangement.

### Method
Async Method

### Class
Window

### Parameters
- **name** (str) - Required - The name to save the arrangement as.

### Returns
- None

```

--------------------------------

### Profile.async_set_advanced_working_directory_pane_setting()

Source: https://iterm2.com/python-api/genindex.html

Sets the advanced working directory pane setting for a profile.

```APIDOC
## Profile.async_set_advanced_working_directory_pane_setting()

### Description
Sets the advanced working directory pane setting for a profile.

### Method
async_set_advanced_working_directory_pane_setting()

### Parameters
No parameters documented in the source.

### Returns
No return value documented in the source.
```

--------------------------------

### Profile.scrollback_with_status_bar

Source: https://iterm2.com/python-api/profile.html

Returns whether text gets appended to scrollback when there is an app status bar.

```APIDOC
## Profile.scrollback_with_status_bar

### Description
Returns whether text gets appended to scrollback when there is an app status bar.

### Returns
A bool
```

--------------------------------

### Profile.scrollback_in_alternate_screen

Source: https://iterm2.com/python-api/profile.html

Returns whether text gets appended to scrollback in alternate screen mode.

```APIDOC
## Profile.scrollback_in_alternate_screen

### Description
Returns whether text gets appended to scrollback in alternate screen mode.

### Returns
A bool
```

--------------------------------

### Profile.async_set_use_transparency_initially

Source: https://iterm2.com/python-api/genindex.html

Asynchronously sets whether to use transparency initially for the profile.

```APIDOC
## Profile.async_set_use_transparency_initially

### Description
Asynchronously sets whether to use transparency initially for the profile.

### Method
async

### Signature
`async_set_use_transparency_initially(value)`

### Parameters
- **value** (bool) - Required - The new value for the use_transparency_initially setting.

### Returns
None
```

--------------------------------

### async_set_scrollback_with_status_bar

Source: https://iterm2.com/python-api/profile.html

Sets whether text gets appended to scrollback when there is an app status bar.

```APIDOC
## async_set_scrollback_with_status_bar

### Description
Sets whether text gets appended to scrollback when there is an app status bar.

### Method
async

### Signature
async_set_scrollback_with_status_bar(value: bool)

### Parameters
- **value** (bool) - Required - A bool.

```

--------------------------------

### async_set_blend

Source: https://iterm2.com/python-api/profile.html

Sets how much the default background color gets blended with the background image.

```APIDOC
## async_set_blend

### Description
Sets how much the default background color gets blended with the background image. The value is in 0 to 1.

### Method
async

### Parameters
- **value** (float) - Required - A float.

```

--------------------------------

### Enable Broadcasting Input with iterm2.async_set_broadcast_domains

Source: https://iterm2.com/python-api/examples/enable_broadcasting.html

Turns on input broadcasting for the first session in each tab of the first window. Creates a BroadcastDomain, adds the first session of each tab, and sets it as the only broadcast domain. Requires an iTerm2 Python API connection.

```python
#!/usr/bin/env python3

import iterm2

async def main(connection):
    app = await iterm2.async_get_app(connection)
    domain = iterm2.broadcast.BroadcastDomain()
    for tab in app.terminal_windows[0].tabs:
        domain.add_session(tab.sessions[0])
    await iterm2.async_set_broadcast_domains(connection, [domain])


iterm2.run_until_complete(main)
```

--------------------------------

### Tab.async_activate

Source: https://iterm2.com/python-api/tab.html

Selects this tab, optionally bringing its window to the front and giving it keyboard focus.

```APIDOC
## async_activate(order_window_front: bool = True) -> None

### Description
Selects this tab. If order_window_front is True, the window containing this tab is brought to the front and given keyboard focus.

### Method
async_activate

### Parameters
- **order_window_front** (bool) - Optional - Whether the window this session is in should be brought to the front and given keyboard focus. Defaults to True.

### Returns
None

### Throws
- RPCException if something goes wrong.

### See Also
- Example "Function Key Tabs"
```

--------------------------------

### async_get_variable

Source: https://iterm2.com/python-api/tab.html

Gets a user-defined variable from the tab. The variable name must begin with 'user.'.

```APIDOC
## async_get_variable

### Description
Gets a user-defined variable from the tab. The variable name must begin with 'user.'.

### Method
async

### Signature
`async def async_get_variable(name: str) -> Any`

### Parameters
- **name** (str) - Required - The variable's name. Must begin with `user.`.

### Returns
Any - The value of the variable.

### Throws
- `RPCException` if something goes wrong.
```

--------------------------------

### async_get_tmux_connection_by_connection_id() (module iterm2)

Source: https://iterm2.com/python-api/genindex.html

Module-level function to get a tmux connection by its connection ID.

```APIDOC
## async_get_tmux_connection_by_connection_id()

### Description
Retrieves a tmux connection by its connection ID.

### Method
Function

### Module
iterm2

### Parameters
- **connection_id** (str) - Required - The ID of the tmux connection.

### Returns
- **TmuxConnection** - The tmux connection object.

```

--------------------------------

### Profile.async_set_touchbar_mappings

Source: https://iterm2.com/python-api/genindex.html

Sets the Touch Bar mappings for a profile.

```APIDOC
## Profile.async_set_touchbar_mappings

### Description
Sets the Touch Bar mappings for a profile.

### Method
async_set_touchbar_mappings

### Class
Profile

### Module
iterm2
```

--------------------------------

### Arrangement.async_list()

Source: https://iterm2.com/python-api/genindex.html

Lists all saved window arrangements.

```APIDOC
## Arrangement.async_list()

### Description
Lists all saved window arrangements.

### Method
Static Async Method

### Class
Arrangement

### Parameters
- None

### Returns
- **list** - A list of arrangement names.

```

--------------------------------

### ColorPreset.async_get_list

Source: https://iterm2.com/python-api/colorpresets.html

Fetches a list of color presets. Returns the names of the color presets.

```APIDOC
## async_get_list

### Description
Fetches a list of color presets.

### Method
async static

### Signature
async_get_list(connection: Connection) -> List[str]

### Parameters
- **connection** (Connection) - Required - An Connection.

### Returns
Names of the color presets.

### See Also
- Example "Get Selected Color Preset"
- Example "Random Color Preset"
```

--------------------------------

### async_get_frame

Source: https://iterm2.com/python-api/window.html

Gets the window's frame. The origin (0,0) is the bottom right of the main screen.

```APIDOC
## async_get_frame

### Description
Gets the window's frame. The origin (0,0) is the bottom right of the main screen.

### Method
async_get_frame

### Returns
This window's frame. This includes window decoration such as the title bar.

### Throws
GetPropertyException if something goes wrong.
```

--------------------------------

### Profile.async_set_advanced_working_directory_window_directory()

Source: https://iterm2.com/python-api/genindex.html

Sets the advanced working directory window directory for a profile.

```APIDOC
## Profile.async_set_advanced_working_directory_window_directory()

### Description
Sets the advanced working directory window directory for a profile.

### Method
async_set_advanced_working_directory_window_directory()

### Parameters
No parameters documented in the source.

### Returns
No return value documented in the source.
```

--------------------------------

### async_get_preference

Source: https://iterm2.com/python-api/preferences.html

Gets a preference by key. Returns the preference value or None if unset and no default exists.

```APIDOC
## async_get_preference

### Description
Gets a preference by key.

### Function Signature
`async def async_get_preference(connection, key: PreferenceKey) -> None | Any`

### Parameters
- **connection** - The connection to the iTerm2 application.
- **key** (PreferenceKey) - The preference key, from the PreferenceKey enum.

### Returns
An object with the preference value, or None if unset and no default exists.

```

--------------------------------

### Profile.use_transparency_initially

Source: https://iterm2.com/python-api/profile.html

Returns whether a window created with this profile respects the transparency setting. If True, use transparency; if False, force the window to be opaque (but it can be toggled with View > Use Transparency).

```APIDOC
## Profile.use_transparency_initially

### Description
Returns whether a window created with this profile respects the transparency setting. If True, use transparency; if False, force the window to be opaque (but it can be toggled with View > Use Transparency).

### Returns
A typing.Optional[bool]
```

--------------------------------

### set_command

Source: https://iterm2.com/python-api/profile.html

Sets the command to run when the session starts. The value is a string giving the command to run.

```APIDOC
## set_command

### Description
Sets the command to run when the session starts. The value is a string giving the command to run.

### Parameters
- **value** (`str`) - Required - A str

```

--------------------------------

### async_set_command

Source: https://iterm2.com/python-api/profile.html

Sets the command to run when the session starts. The value is a string giving the command to run.

```APIDOC
## async_set_command

### Description
Sets the command to run when the session starts. The value is a string giving the command to run.

### Method
async_set_command

### Parameters
- **value** (str) - Required - A string giving the command to run.

```

--------------------------------

### Profile.initial_directory_mode

Source: https://iterm2.com/python-api/profile.html

Returns whether to use a custom (not home) initial working directory.

```APIDOC
## Profile.initial_directory_mode

### Description
Returns whether to use a custom (not home) initial working directory.

### Returns
An InitialWorkingDirectory
```

--------------------------------

### Profile.async_set_place_prompt_at_first_column()

Source: https://iterm2.com/python-api/genindex.html

Sets whether the prompt is placed at the first column for a profile asynchronously.

```APIDOC
## Profile.async_set_place_prompt_at_first_column()

### Description
Sets whether the prompt is placed at the first column for a profile asynchronously.

### Method
async_set_place_prompt_at_first_column

### Class
Profile

### Module
iterm2

### Reference
[iterm2.Profile.async_set_place_prompt_at_first_column](https://iterm2.com/python-api/profile.html#iterm2.Profile.async_set_place_prompt_at_first_column)
```

--------------------------------

### async_open_popover

Source: https://iterm2.com/python-api/statusbar.html

Open a popover with a webview.

```APIDOC
## async_open_popover

### Description
Open a popover with a webview.

### Method
async

### Parameters
- **session_id** (str) - Required - The session identifier.
- **html** (str) - Required - A string containing HTML to show.
- **size** (Size) - Required - The desired size of the popover, a Size.

### Returns
Coroutine
```

--------------------------------

### Get current window

Source: https://iterm2.com/python-api/tutorial/example.html

Fetches the current terminal window from the app. Returns None if there are no terminal windows.

```python
window = app.current_window
```

--------------------------------

### Session.all_proxy(connection)

Source: https://iterm2.com/python-api/session.html

Static method to get a proxy for all sessions, including those not yet created, for registering notifications.

```APIDOC
## Session.all_proxy(connection)

### Description
Returns a proxy for all sessions, including those not yet created, for registering notifications.

### Method
Static method

### Parameters
- **connection** (Connection) - Required - The connection to iTerm2.

### Returns
A proxy for all sessions.
```

--------------------------------

### Arrangement.async_save

Source: https://iterm2.com/python-api/arrangement.html

Saves all windows as a new arrangement. Replaces an existing arrangement with the same name.

```APIDOC
## Arrangement.async_save

### Description
Saves all windows as a new arrangement. Replaces the arrangement with the given name if it already exists.

### Method
async static

### Signature
async_save(connection: Connection, name: str)

### Parameters
- **connection** (Connection) - Required - The name of the arrangement.
- **name** (str) - Required - The name of the arrangement.

### Throws
SavedArrangementException
```

--------------------------------

### Session.active_proxy(connection)

Source: https://iterm2.com/python-api/session.html

Static method to get a proxy for the currently active session, used for registering notifications.

```APIDOC
## Session.active_proxy(connection)

### Description
Returns a proxy for the currently active session, which can be used to register notifications.

### Method
Static method

### Parameters
- **connection** (Connection) - Required - The connection to iTerm2.

### Returns
A proxy for the currently active session.
```

--------------------------------

### set_blend

Source: https://iterm2.com/python-api/profile.html

Sets how much the default background color gets blended with the background image. The value is in 0 to 1.

```APIDOC
## set_blend(value: float)

### Description
Sets how much the default background color gets blended with the background image. The value is in 0 to 1.

### Parameters
- **value** (float) - Required - A float

```

--------------------------------

### Tab.async_move_to_window()

Source: https://iterm2.com/python-api/genindex.html

Moves the tab to a new window.

```APIDOC
## Tab.async_move_to_window()

### Description
Moves the tab to a new window.

### Method
Async Method

### Class
Tab

### Parameters
- **window** (Window) - Required - The destination window.

### Returns
- None

```
Tokens:
Raw