iTerm2

https://iterm2.com/
Admin
iTerm2 is a powerful, modern replacement for the macOS Terminal, offering advanced features for...
Tokens:555,880
Snippets:5,901
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Full example script: iterm2 async_create_tab

Source: https://iterm2.com/python-api/_sources/tutorial/example.rst.txt

The complete example script that iTerm2 provides, minus some comments. It connects to the running iTerm2 app, gets the current window, and creates a new tab if a window exists; otherwise it prints "No current window".

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

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

### Full example script (iterm2.run_until_complete)

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

The complete example script that iTerm2 provides. It imports iterm2, defines an async main(connection) that gets the app, checks for a current window, creates a tab if one exists, and otherwise prints "No current window", then runs it with iterm2.run_until_complete(main).

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

```

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

### Bash examples for custom buttons

Source: https://iterm2.com/documentation-escape-codes.html

Bash examples for creating a custom button and invalidating all custom buttons.

```bash
# Create a custom button with code 42 and a star icon
echo -ne "\033]1337;Button=type=custom;code=42;icon=star.fill\a"

# Invalidate all custom buttons
echo -ne "\033]1337;Button=type=custom\a"

```

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

### Install dependencies with brew and pip3

Source: https://iterm2.com/python-api/_sources/examples/launch_and_run.rst.txt

Install the dependencies needed to run the script from the command line: iterm2 and pyobjc via pip3, after installing Python 3 with Homebrew.

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

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

### Install Shell Integration for fish

Source: https://iterm2.com/documentation-shell-integration.html

Manual installation for fish: download the integration script to ~/.iterm2_shell_integration.fish, then add the source command to the end of ~/.config/fish/config.fish.

```bash
curl -L https://iterm2.com/shell_integration/fish \
-o ~/.iterm2_shell_integration.fish
```

```fish
source ~/.iterm2_shell_integration.fish
```

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

### Install Shell Integration for zsh

Source: https://iterm2.com/documentation-shell-integration.html

Manual installation for zsh: download the integration script to ~/.iterm2_shell_integration.zsh, then add the source command to the end of ~/.zshrc.

```bash
curl -L https://iterm2.com/shell_integration/zsh \
-o ~/.iterm2_shell_integration.zsh
```

```zsh
source ~/.iterm2_shell_integration.zsh
```

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

### Dynamic profile example for SSH hosts

Source: https://iterm2.com/3.7/documentation-dynamic-profiles.html

A JSON example of a dynamic profile file that defines a list of profiles for SSH connections to various hosts. The hostname is used as the Guid to simplify file construction. Each profile sets the Custom Command to Yes and provides the ssh command in the Command field.

```json
{
  "Profiles": [
    {
       "Name": "foo.example.com",
       "Guid": "foo.example.com",
       "Custom Command" : "Yes",
       "Command" : "ssh foo.example.com",
    },
  ]
}
```

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

### 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 starting point for accessing windows and other application-global data.

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

### Description
Returns the app singleton, creating it if needed. This is the starting point for accessing windows and other application-global data.

### Method
async function

### Parameters
- **connection** (`iterm2.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. Defaults to True.

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

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

### Get Selected Color Preset with iterm2

Source: https://iterm2.com/python-api/_sources/examples/current_preset.rst.txt

Run with pip3 install iterm2 and execute from command line or from the Scripts menu, viewing output in the Script Console. Prints the preset name or None.

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

import iterm2

def ColorsUnequal(profile_color, preset_color):
    return (round(profile_color.red) != round(preset_color.red) or
            round(profile_color.green) != round(preset_color.green) or
            round(profile_color.blue) != round(preset_color.blue) or
            round(profile_color.alpha) != round(preset_color.alpha) or
            profile_color.color_space != preset_color.color_space)

def ProfileUsesPreset(profile, preset):
    for preset_color in preset.values:
        key = preset_color.key
        profile_color = profile.get_color_with_key(key)
        if ColorsUnequal(profile_color, preset_color):
            return False
    return True

async def PresetForProfile(connection, profile):
    presets=await iterm2.ColorPreset.async_get_list(connection)
    for preset_name in presets:
        preset=await iterm2.ColorPreset.async_get(connection, preset_name)
        if ProfileUsesPreset(profile, preset):
          return preset_name
    return None


async def main(connection):
    app = await iterm2.async_get_app(connection)
    session=app.current_terminal_window.current_tab.current_session
    profile=await session.async_get_profile()
    print(await PresetForProfile(connection, profile))

iterm2.run_until_complete(main)
```

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

### Invoke create_window with literal arguments

Source: https://iterm2.com/documentation-scripting-fundamentals.html

Invokes the create_window function with the initialDirectory parameter set to the literal string "/etc" and profileName set to "Default". Parameter order does not matter because every parameter is named.

```text
create_window(initialDirectory: "/etc", profileName: "Default")

```

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

### Query with quoted string and trailing dollar sign

Source: https://iterm2.com/3.7/documentation-one-page.html

Matches a profile named "XGeorge's Linux Machine", unlike the previous example, because the caret is omitted so the match need not start at the beginning.

```text
name:"George's Linux Machine"$

```

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

### Copy a command block with iterm2:copy-block

Source: https://iterm2.com/3.7/documentation-url-scheme.html

Copies the text of a command block (the output of a single command, when Shell Integration is installed) to the clipboard. The guid parameter is optional and defaults to the current session if omitted; block is required and identifies the block to copy.

```text
iterm2:copy-block?guid=<session-guid>&block=<block-id>

```

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

### Install gptline with pip3

Source: https://iterm2.com/downloads.html

Install the gptline command-line client using pip3. Requires an OpenAI API key that works with gpt-4, set in the OPENAI_KEY environment variable.

```bash
pip3 install gptline
```

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

### Install Shell Integration from iTerm2 menu

Source: https://iterm2.com/documentation-utilities.html

Install the Shell Integration and Utilities Package from the iTerm2 > Install Shell Integration menu. The Utilities Package is optional and can be installed alongside Shell Integration.

```text
iTerm2 > Install Shell Integration
```

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

### async_activate()

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

Activates the window by giving it keyboard focus and ordering it to the front.

```APIDOC
## 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

### Endpoint
Window.async_activate()

### Parameters
None

### Returns
None

```

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

### async_create(connection, profile, command, profile_customizations)

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

Creates a new terminal window with optional profile, command, and profile customizations.

```APIDOC
## async_create(connection: iterm2.connection.Connection, profile: Optional[str] = None, command: Optional[str] = None, profile_customizations: Union[None, iterm2.profile.LocalWriteOnlyProfile] = None) -> Optional[iterm2.window.Window]

### Description
Creates a new window. This is a static async method.

### Method
async static

### Endpoint
Window.async_create(connection, profile, command, profile_customizations)

### Parameters
- **connection** (Connection) - Required - A `Connection`.
- **profile** (Optional[str]) - Optional - The name of the profile to use for the new window.
- **command** (Optional[str]) - Optional - A command to run in lieu of the shell in the new session. Mutually exclusive with profile_customizations.
- **profile_customizations** (Union[None, 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.

```

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

### Install Shell Integration for bash

Source: https://iterm2.com/documentation-shell-integration.html

Manual installation for bash: download the integration script to ~/.iterm2_shell_integration.bash, then add the source command to the end of ~/.bash_profile or ~/.profile. Place it at the end because other scripts may overwrite settings like PROMPT_COMMAND.

```bash
curl -L https://iterm2.com/shell_integration/bash \
-o ~/.iterm2_shell_integration.bash
```

```bash
source ~/.iterm2_shell_integration.bash
```

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

### Profile.async_get

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

Fetches all profiles with the specified GUIDs, or all profiles if no GUIDs are provided.

```APIDOC
## [GET] /profiles

### Description
Fetches all profiles with the specified GUIDs.

### Method
GET

### Endpoint
/profiles

### Parameters
#### Query Parameters
- **guids** (list) - Optional - The profiles to get, or if None then all will be returned.

### Response
#### Success Response (200)
- **profiles** (List[Profile]) - A list of Profile objects.

#### Response Example
{
  "profiles": [
    {
      "guid": "string"
    }
  ]
}
```

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

### Example shell prompt: george@example.com:/home/george%

Source: https://iterm2.com/3.7/documentation-shell-integration.html

Shows the shell prompt format that the trigger regular expressions are designed to match. The prompt exposes username, hostname, and working directory.

```text
george@example.com:/home/george%

```

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

### Force title reevaluation with a periodic user-defined variable update

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

Sets the session title to its age in seconds by periodically updating a user-defined variable. Requires an external action (timer, network request, or user action) to change a user-defined variable so the title provider is forced to reevaluate. The example registers a title provider RPC and starts a background task that increments the age variable every second.

```python
import asyncio
import iterm2

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

    async def redraw_title_provider_periodically(session_id):
       try:
            age = 0
            session = app.get_session_by_id(session_id)
            while True:
                await asyncio.sleep(1)
                # When the session ends, this will raise an exception.
                await session.async_set_variable(
                    "user.session_age_in_seconds", age)
                age += 1
       except Exception as e:
           traceback.print_exc()
       finally:
            del tasks[session_id]

    @iterm2.TitleProviderRPC
    async def age_in_seconds_title(
            session_id=iterm2.Reference(
```
Tokens:
Raw