The provided paper describes it2, a powerful command-line interface (CLI) designed for comprehensive control and interaction with iTerm2, leveraging its built-in Python API. The tool aims to provide a tmux- or screen-like experience for iTerm2 users, enabling programmatic management of terminal sessions, windows, and tabs.

Core Methodology:
it2 operates by acting as a shell-level abstraction over the iTerm2 Python API. When an it2 command is executed, the CLI translates this command into corresponding Python API calls. These calls directly interface with a running iTerm2 instance, enabling the manipulation of its internal state and behavior. For this mechanism to function, iTerm2 must be running, and its Python API must be explicitly enabled within iTerm2 preferences (Preferences > General > Magic > Enable Python API). The tool's architecture, as revealed by its src directory, includes distinct modules for various command categories (e.g., session.py, window.py, tab.py, profile.py, app.py, monitor.py) and a core directory handling connection.py and session_handler.py. This modular design suggests that it2 establishes a connection to the iTerm2 application via its API and then dispatches commands to the appropriate handler, which in turn invokes the specific iTerm2 API functions. The tool also supports user-defined configurations through a YAML file (~/.it2rc.yaml), allowing for the creation of custom "profiles" (sequences of it2 commands to set up complex layouts or environments) and command aliases.

Key Features and Capabilities:

1. Session Management:
   • Input/Execution: Send arbitrary text (it2 send "text") or execute commands (it2 run "command") within a session. The run command automatically appends a newline, simulating pressing Enter.
   • Targeting: Commands can target the current session, a specific session by ID (--session <id>), or all sessions (--all).
   • Pane Splitting: Split the current pane horizontally (it2 session split) or vertically (it2 session split -v or it2 vsplit).
   • Lifecycle Control: List all active sessions (it2 session list), close the current session (it2 session close), restart a session (it2 session restart), or clear its screen (it2 session clear).

2. Window Control:
   • Creation & Management: Create new windows (it2 window new), list existing windows (it2 window list), close the current window (it2 window close), or focus a specific window by ID ($it2 window focus <id>$).
   • Manipulation: Move (it2 window move 100 200), resize (it2 window resize 800 600), or toggle fullscreen mode (it2 window fullscreen on).
   • Arrangements: Save and restore window layouts as named arrangements (it2 window arrange save "name", it2 window arrange restore "name").

3. Tab Operations:
   • Management: Create new tabs (it2 tab new), list all tabs (it2 tab list), close the current tab (it2 tab close), or select a specific tab by ID ($it2 tab select <id>$).
   • Navigation: Navigate between tabs sequentially (it2 tab next, it2 tab prev) or jump to a tab by its index (it2 tab goto 2).

4. Profile Management:
   • Interact with iTerm2 profiles: list all available profiles (it2 profile list), show details of a specific profile (it2 profile show "Default"), or apply a profile to a session/window (it2 profile apply "MyProfile").
   • Modify profile properties directly (it2 profile set "MyProfile" font-size 14).

5. Application Control:
   • iTerm2 Application State: Activate (bring to front) (it2 app activate), hide (it2 app hide), display iTerm2 version (it2 app version), or show/set the current theme (it2 app theme, it2 app theme dark).
   • Broadcasting: Enable or disable input broadcasting across multiple sessions (it2 app broadcast on/off) and manage broadcast groups (it2 app broadcast add session1 session2).

6. Monitoring:
   • Real-time Observation: Monitor session output (it2 monitor output -f, with pattern filtering -p "ERROR"), keystrokes (it2 monitor keystroke, with regex filtering -p "^[a-z]+__INLINE_CODE_60__quot;), session/application variables (it2 monitor variable lastCommand), and shell prompts (requires shell integration) (it2 monitor prompt).

7. Configuration:
   • Users can define custom profiles and command aliases in ~/.it2rc.yaml. Profiles can encapsulate complex sequences of commands, pane splits, and commands for each pane (e.g., setting up a development environment with multiple npm commands in split panes). Aliases provide shorthand for frequently used it2 commands. Configurations can be loaded ($it2 load <profile_name>$) or reloaded (it2 config-reload).

Error Handling:
it2 provides specific error codes for different failure scenarios:

• 0: Success.
• 1: General error.
• 2: Connection error (iTerm2 not running or API not enabled).
• 3: Target not found (e.g., specified session, window, or tab does not exist).
• 4: Invalid arguments provided to a command.

Installation and Requirements:
it2 is installable via pip (pip install it2) or uvx (uvx it2). It requires macOS with iTerm2 3.3.0 or later and Python 3.9+. The iTerm2 Python API must be enabled.