### Manual Fish Shell Integration Setup

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

Manually install fish shell integration by downloading the script and sourcing it at the end of your ~/.config/fish/config.fish file.

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

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

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

### Minimal Dynamic Profile JSON Example

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

A minimal example of a dynamic profile configuration in JSON format. It includes the required 'Name' and 'Guid' fields for a profile.

```json
{
  "Profiles": [
    {
      "Name": "Example",
      "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958"
    }
  ]
}

```

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

### Minimal Dynamic Profile Example

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

A basic example of a valid Dynamic Profile plist containing the required Guid and Name fields.

```json
{
  "Profiles": [
    {
      "Name": "Example",
      "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958"
    }
  ]
}
```

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

### Manual Bash Shell Integration Setup

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

Manually install bash shell integration by downloading the script and sourcing it in your .bash_profile or .profile. Ensure it's loaded after other scripts that might modify PROMPT_COMMAND.

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

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

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

### Manual Tcsh Shell Integration Setup

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

Manually install tcsh shell integration by downloading the script and sourcing it at the end of your ~/.login file.

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

```tcsh
source ~/.iterm2_shell_integration.tcsh
```

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

### Install Shell Integration Script

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

Use this command to download and execute the shell integration installer script. This is the recommended method for most users.

```bash
curl -L https://iterm2.com/shell_integration/install_shell_integration.sh | bash
```

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

### Manual Zsh Shell Integration Setup

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

Manually install zsh shell integration by downloading the script and sourcing it at the end of your ~/.zshrc file.

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

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

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

### Manual Xonsh Shell Integration Setup

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

Manually install xonsh shell integration by downloading the script to the ~/.config/xonsh/rc.d/ directory. Xonsh automatically loads scripts from this directory.

```xonsh
mkdir -p ~/.config/xonsh/rc.d
curl -L https://iterm2.com/shell_integration/xonsh \
-o ~/.config/xonsh/rc.d/iterm2.xsh
```

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

### Install iTerm2 Dependencies

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

Before running the script, ensure you have Python 3, pip3, and PyObjC installed. This setup is necessary for the script to function correctly.

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

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

### Example Shell Prompt

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

This is an example of a shell prompt that exposes username, hostname, and working directory.

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

```

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

### Install aiohttp for TargetedInput Script

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

Install the 'aiohttp' package for the TargetedInput script. This command should be run after creating the script as a 'Full Environment' script.

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

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

### Bash Example: Create and Invalidate Custom Buttons

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

Bash examples demonstrating how to create a custom button with a specific code and icon, and how to invalidate 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"

```

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

### Example Shell Prompt

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

A sample shell prompt format used for demonstrating trigger configuration.

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

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

### Example iTerm2 Python Script

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

This script demonstrates basic interaction with iTerm2, such as getting the current window and creating a new tab. It requires the iterm2 Python module and uses asyncio for asynchronous operations.

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

```

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

### Toggle Cursor Guide

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

Enable or disable the cursor guide line.

```text
OSC 1337 ; HighlightCursorLine=[boolean] ST
```

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

### Manually Install Shell Integration

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

Downloads and sources shell-specific integration scripts for various Unix shells.

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

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

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

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

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

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

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

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

```bash
mkdir -p ~/.config/xonsh/rc.d
curl -L https://iterm2.com/shell_integration/xonsh \
-o ~/.config/xonsh/rc.d/iterm2.xsh
```

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

### Example error message with line number

Source: https://iterm2.com/documentation-captured-output.html

Sample output line used to demonstrate coprocess execution.

```text
filename.c:20:9 error: use of undeclared identifier 'foo'
```

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

### Regex to Capture Directory

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

This regular expression extracts the directory from the example prompt, capturing the path before the '%'.

```regex
^\w+@[\w.]+:[^%]+%
```

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

### Window and Startup Configuration

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

Settings for window management, tab bars, and startup behavior.

```APIDOC
## Window and Startup Settings

### Description
Manage window behavior, tab bar visibility, and startup preferences.

### Parameters
#### Request Body
- **LEFT_TAB_BAR_WIDTH** (float) - Optional - Width of left-side tab bar.
- **NATIVE_FULL_SCREEN_WINDOWS** (boolean) - Optional - Use native full screen window.
- **OPEN_DEFAULT_ARRANGEMENT_AT_START** (boolean) - Optional - Open default arrangement at startup.
- **OPEN_PROFILES_WINDOW_AT_START** (boolean) - Optional - Open the profiles window at startup.
- **PROMPT_ON_QUIT** (boolean) - Optional - Prompt before quitting.
- **QUIT_WHEN_ALL_WINDOWS_CLOSED** (boolean) - Optional - Quit automatically when all terminal windows are closed.
```

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

### iTerm2 Python API Overview

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

This section provides an overview of the iTerm2 Python API, its purpose, and how to get started with scripting.

```APIDOC
## iTerm2 Python API

### Description
iTerm2 offers a Python package which makes it easy to write Python scripts that control iTerm2 and extend its behavior.

### Getting Started
Start by following the tutorial, which gives a step-by-step guide to writing a script and describes the architecture of iTerm2’s scripting system.

### Example Code
Visit the examples for a collection of working examples.

### Class Reference
The Python API provides access to various iTerm2 components through the following classes:
- Alert
- App
- Arrangement
- Broadcast
- Color
- Color Presets
- Custom Control Sequences
- Connection
- Focus
- Keyboard
- Life Cycle
- Main Menu
- Preferences
- Profile
- Prompt
- Registration
- Screen
- Selection
- Session
- Status Bar
- Tab
- Tmux
- Tool
- Transaction
- Utilities
- Variables
- Window
```

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

### Application Scripting - Creating Windows

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

Examples of how to create new windows using AppleScript, with options for default or specific profiles, and overriding commands.

```APIDOC
## Application Scripting - Creating Windows

### Description
These commands create new windows using AppleScript. You can specify a default profile, a named profile, or override the default command.

### Method
AppleScript

### Endpoints
N/A (Scripting commands)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```applescript
tell application "iTerm2"
  create window with default profile
end tell
```

### Response
#### Success Response (200)
Returns a reference to the newly created window.

#### Response Example
```applescript
-- Returns a reference to the new window
set newWindow to (create window with default profile)
```

### Additional Commands

#### `create hotkey window with profile "_name_ "`
Creates a hotkey window with the specified profile. The profile must be configured to have a hotkey.
*   **Example:** `create hotkey window with profile "Hotkey Window"`

#### `create window with default profile command "_command_ "`
Creates a window with the default profile. If a command is specified, it overrides the profile's default command.
*   **Example:** `set newWindow to (create window with default profile command "ls -l -R /")`

#### `create window with profile "_name_ "`
Creates a window with a named profile.

#### `create window with profile "_name_ " command "_command_ "`
Creates a window with a named profile. If a command is specified, it overrides the profile's default command.
*   **Example:** `set newWindow to (create window with profile "Name Of Some Profile")`
*   **Example:** `set newWindow to (create window with profile "Name Of Some Profile" command "ls -l -R /")`
```

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

### Main Execution Logic

Source: https://iterm2.com/utilities/imgcat

Initializes script state, checks for standard input, and verifies dependencies.

```bash
if [ -t 0 ]; then
    has_stdin=f
else
    has_stdin=t
fi

# Show help if no arguments and no stdin.
if [ $has_stdin = f ] && [ $# -eq 0 ]; then
    show_help
    exit
fi

check_dependency base64
check_dependency wc
file_type=""
legacy=0
```

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

### SSH Host Dynamic Profiles Example

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

This JSON structure defines dynamic profiles for SSH connections. Each profile uses the hostname as its GUID and specifies a custom command to initiate the SSH connection.

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

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

### Install pyobjc Dependency

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

Command to install the pyobjc library required for launching iTerm2 from a script.

```bash
pip3 install pyobjc
```

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

### Keystroke Filtering Example

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

This example demonstrates how to prevent iTerm2 from handling all control-key combinations by creating a KeystrokeFilter.

```APIDOC
## Prevent iTerm2 from handling all control-key combinations.

### Description
This code snippet shows how to define a keystroke pattern that matches any control-key combination and then use this pattern to create a filter that prevents iTerm2 from processing these keystrokes.

### Method
Asynchronous Python script using iTerm2 API

### Endpoint
N/A (Local script execution)

### Parameters
N/A

### Request Example
```python
import iterm2

async def main(connection):
    ctrl = iterm2.KeystrokePattern()
    ctrl.required_modifiers = [iterm2.Modifier.CONTROL]
    ctrl.keycodes = [keycode for keycode in iterm2.Keycode]

    filter = iterm2.KeystrokeFilter(connection, [ctrl])
    async with filter as mon:
        await iterm2.async_wait_forever()

iterm2.run_forever(main)
```

### Response
N/A (This is a configuration script, not a request/response API)

```

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

### Install iTerm2 Python API Dependencies

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

Install the required dependencies for the iTerm2 Python API using Homebrew and pip.

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

```

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

### Invoke a function with named parameters

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

Demonstrates the syntax for calling a function with specific arguments for initial directory and profile name.

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

```text
create_window(initialDirectory: path, profileName: "Default")
```

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

### iTerm2 Profile Search Syntax Examples

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

Illustrates iTerm2's profile search syntax, demonstrating substring matching, operator usage, quoting for ordered phrases, and anchoring with caret (^) for prefixes and dollar sign ($) for suffixes.

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

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

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

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

```text
name:^George's
```

```text
name:George's$
```

```text
name:^George's$
```

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

### Full iTerm2 Example Script

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

This script demonstrates basic iTerm2 automation by creating a new tab in the current window. It requires the 'iterm2' Python module and an active iTerm2 instance.

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

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

### Example iTerm2 Feature String

Source: https://iterm2.com/feature-reporting

This example string demonstrates the encoding of features, where 'Ab', 'Cd', 'Ef', 'G', and 'H' are present, and 'Ef' has a value of 12.

```plaintext
AbCdEf12GH

```

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

### Toggle Cursor Guide in Vim

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

This escape sequence can be added to your .vimrc to toggle the cursor guide feature in iTerm2. The first line enables it, and the second line disables it.

```vim
let &t_ti.="\<Esc>]1337;HighlightCursorLine=true\x7"
let &t_te.="\<Esc>]1337;HighlightCursorLine=false\x7"

```

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

### Custom Toolbelt Tool for Targeted Input

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

Demonstrates creating a custom toolbelt tool that can broadcast domains and send targeted input to specific panes. This involves defining custom commands.

```Python
# This is a conceptual example. Actual implementation requires iTerm2's toolbelt API.

class CustomToolbeltTool:
    def __init__(self):
        self.name = "MyCustomTool"

    def broadcast_domain(self, domain):
        print(f"Broadcasting domain: {domain}")
        # iTerm2 API call to broadcast

    def send_input(self, target_pane, input_string):
        print(f"Sending input to pane {target_pane}: {input_string}")
        # iTerm2 API call to send input

# Example usage:
# tool = CustomToolbeltTool()
# tool.broadcast_domain("example.com")
# tool.send_input("pane_1", "ls -l\n")
```

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

### Start tmux in iTerm2 Integration Mode

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

Use the -CC argument when invoking tmux to start it in iTerm2's compatibility mode. This enables a native iTerm2 window experience for your tmux sessions.

```bash
tmux -CC
```

```bash
tmux -CC attach
```

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

### Scripting - Autolaunch and User-Defined Scripts

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

Information on how iTerm2 handles autolaunching AppleScripts on startup and how to load user-defined scripts from specific directories.

```APIDOC
## Scripting - Autolaunch and User-Defined Scripts

### Description
This section describes how iTerm2 manages script execution, including scripts that automatically run on startup and scripts that can be launched manually from the 'Scripts' menu.

### Method
File System / Application Configuration

### Endpoints
N/A

### Parameters
None

### Autolaunching Scripts
iTerm2 looks for an AppleScript file named `AutoLaunch.scpt` in the following directories:
1.  `~/Library/Application Support/iTerm2/Scripts/AutoLaunch.scpt` (Preferred)
2.  `~/Library/Application Support/iTerm/Scripts/AutoLaunch.scpt` (Legacy path)
If found, the script is launched and executed on application startup.

### User-Defined Scripts
User-defined scripts can be launched from the 'Scripts' menu. These scripts must be stored in the `~/Library/Application Support/iTerm/Scripts` directory. This directory will be checked by iTerm2 on startup. Scripts must have either a `.scpt` or `.app` extension.

### Setup
1.  Create the directory `~/Library/Application Support/iTerm/Scripts` if it does not exist.
2.  Place your `.scpt` or `.app` script files in this directory.
3.  iTerm2 will automatically detect and list these scripts in the 'Scripts' menu.
```

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

### Shell Integration Utilities

Source: https://iterm2.com/downloads/stable/iTerm2-3_5_0.changelog

Install shell integration and utilities to access new command-line apps like 'it2tip' (tip of the day). Automatic injection is now standard for login shells.

```bash
it2tip
```

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

### Bash Example: Set Badge with Session Name and Git Branch

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

An example in bash that sets the badge to display the current session name and the git branch. It uses `printf` and `base64` to encode the desired format string.

```bash
# Set badge to show the current session name and git branch, if any is set.
printf "\e]1337;SetBadgeFormat=%s\a" \
  $(echo -n "\(session.name) \(user.gitBranch)" | base64)
```

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

### FTCS_COMMAND_EXECUTED

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

Sent just before the start of command output.

```text
OSC 133 ; C ST

```

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

### Help Documentation Function

Source: https://iterm2.com/utilities/imgcat

Displays usage instructions and command-line options for the imgcat utility.

```bash
function show_help() {
    errcho
    errcho "Usage: imgcat [-p] [-n] [-W width] [-H height] [-r] [-s] [-u] [-t file-type] [-f] filename ..."
    errcho "       cat filename | imgcat [-W width] [-H height] [-r] [-s]"
    errcho
    errcho "Display images inline in the iTerm2 using Inline Images Protocol"
    errcho
    errcho "Options:"
    errcho
    errcho "    -h, --help                      Display help message"
    errcho "    -p, --print                     Enable printing of filename or URL after each image"
    errcho "    -n, --no-print                  Disable printing of filename or URL after each image"
    errcho "    -u, --url                       Interpret following filename arguments as remote URLs"
    errcho "    -f, --file                      Interpret following filename arguments as regular Files"
    errcho "    -t, --type file-type            Provides a type hint"
    errcho "    -r, --preserve-aspect-ratio     When scaling image preserve its original aspect ratio"
    errcho "    -s, --stretch                   Stretch image to specified width and height (this option is opposite to -r)"
    errcho "    -W, --width N                   Set image width to N character cells, pixels or percent (see below)"
    errcho "    -H, --height N                  Set image height to N character cells, pixels or percent (see below)"
    errcho "    -l, --legacy                    Use legacy protocol that sends the whole image in a single control sequence"
    errcho
    errcho "    If you don't specify width or height an appropriate value will be chosen automatically."
    errcho "    The width and height are given as word 'auto' or number N followed by a unit:"
    errcho "        N      character cells"
    errcho "        Npx    pixels"
    errcho "        N%     percent of the session's width or height"
    errcho "        auto   the image's inherent size will be used to determine an appropriate dimension"
    errcho
    errcho "    If a type is provided, it is used as a hint to disambiguate."
    errcho "    The file type can be a mime type like text/markdown, a language name like Java, or a file extension like .c"
    errcho "    The file type can usually be inferred from the extension or its contents. -t is most useful when"
    errcho "    a filename is not available, such as whe input comes from a pipe."
    errcho
    errcho "Examples:"
    errcho
    errcho "    $ imgcat -W 250px -H 250px -s avatar.png"
    errcho "    $ cat graph.png | imgcat -W 100%"
    errcho "    $ imgcat -p -W 500px -u http://host.tld/path/to/image.jpg -W 80 -f image.png"
    errcho "    $ cat url_list.txt | xargs imgcat -p -W 40 -u"
    errcho "    $ imgcat -t application/json config.json"
}
```

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

### FTCS_PROMPT

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

Sent just before the start of a shell prompt.

```text
OSC 133 ; A ST

```

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

### Get Preference

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

Retrieves the value of a specific iTerm2 preference.

```APIDOC
## GET /api/preferences/{key}

### Description
Retrieves the value of a specific iTerm2 preference.

### Method
GET

### Endpoint
/api/preferences/{key}

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the preference to retrieve.

### Response
#### Success Response (200)
- **value** (any) - The current value of the preference.

#### Response Example
```json
{
  "value": "true"
}
```
```

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

### iTerm2 Scripting Fundamentals

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

Information on how to store and launch user-defined scripts, and how iTerm2 handles autolaunching scripts on startup.

```APIDOC
## Autolaunching Scripts

### Description
On startup, iTerm2 looks for an AppleScript file named `AutoLaunch.scpt` in specific directories and executes it if found.

### Method
File System / AppleScript

### Endpoint
N/A

### Parameters
None

### Request Example
Place `AutoLaunch.scpt` in one of the following directories:
- `~/Library/Application Support/iTerm2/Scripts/AutoLaunch.scpt` (preferred)
- `~/Library/Application Support/iTerm/Scripts/AutoLaunch.scpt` (legacy)

### Response
N/A

---

## User-Defined Scripts

### Description
Supports launching user-defined scripts from the "Scripts" menu. Scripts must be stored in a specific directory and have a `.scpt` or `.app` extension.

### Method
File System / AppleScript

### Endpoint
N/A

### Parameters
None

### Request Example
1. Create the directory: `~/Library/Application Support/iTerm/Scripts/`
2. Place your script files (e.g., `MyScript.scpt` or `MyScript.app`) in this directory.
3. iTerm2 will detect these scripts on startup and make them available in the "Scripts" menu.

### Response
N/A
```

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

### Launch iTerm2 with Custom Suite

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

Run multiple concurrent instances of iTerm2 with separate configurations by passing the -suite argument.

```bash
iTerm2.app/Contents/MacOS/iTerm2 -suite <name>
```

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

### Get Prompt By ID

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

Fetches a Prompt by its unique ID.

```APIDOC
## Get Prompt By ID

### Description
Fetches a Prompt by its unique ID.

### Parameters
- **connection** (iterm2.connection.Connection): The connection to iTerm2.
- **session_id** (str): The Session ID the prompt belongs to.
- **prompt_unique_id** (str): The unique ID of the prompt.

### Returns
The prompt if one exists or else None.

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