# Iterm2 > - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) --- # Source: https://iterm2.com/documentation-ai-chat.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # AI Chat AI Chat offers a chat window with a large language model that can optionally interact with iTerm2's windows. When you create a new chat by selecting **Window > AI Chat** or clicking the `+` in the AI Chat window, the AI agent is not offered any visibility into iTerm2's windows. ## Linked Sessions You may link a session to a chat. This may give the AI information about the contents of your windows depending on which permissions are enabled. To view permissions, click the info button in the chat toolbar. Any permission with a check mark is granted. Any permission with a dash is "ask before using". Permissions with neither mean "always deny" and the AI agent will not be offered functions related to those categories. Selecting an item in the info menu rotates the permission setting to the next value. The order is Never -> Ask -> Always -> Never. The permission categories are: #### Check Terminal State This exposes information about the linked terminal to AI, including the current directory, user shell, the current or last command and its exit status, the size of the terminal window, the host you are SSHed to (if any), and the current username. #### Run Commands This makes functions available to AI that let it execute commands on your behalf. #### Type for You This makes functions available to AI that let it send keystrokes to the terminal. #### View History This exposes your command history in the linked session to AI #### View Manpages This lets AI view manpages. If you are using ssh integration, man pages from the remote host may be viewed by it. #### Write to Clipboard This makes functions available to AI that let it write to the clipboard. #### Write to filesystem This makes functions available to AI that let it write to the filesystem. #### Act in Web Browser This makes functions available to AI that let it view the contents of the current web page (applicable only in browser profiles). ### Send Commands and Output Automatically When enabled, terminal contents are automatically sent to AI. This can be useful when you need a lot of help completing a task. Consider also the Codecierge tool in the Toolbelt, which is intended specifically for completing multi-step tasks. ## Explain Output When you select **Edit > Explain Output with AI** then a new chat is created and the session is automatically linked. The terminal contents may be annotated with explanations. ## Toolbar The AI Chat window's toolbar shows different icons depending on the capabilities of the current model. When **Settings > General > AI > Always use the recommended model from: ...** is enabled you will get a model selector in the toolbar. A globe icon allows you to grant web search permission. If the selected model supports reasoning then a lightbulb icon in the toolbar allows you to enable reasoning mode. This is generally pretty slow. ## Context Menu You can right-click on a message that you sent to edit, copy, or fork the conversation. Edit is destructive and well erase messages below that point. Fork creates a new chat with messages prior to the clicked-on message. ## Prompts You can edit the prompts in **Settings > General > AI > Prompts**. You'll see that there are different prompts depending on what kind of access the agent has to the window contents. --- # Source: https://iterm2.com/documentation-automatic-profile-switching.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Automatic Profile Switching iTerm2 can use information it knows about your current path, host name, user name, and foreground job name to change profiles. For example, your window's background color or the terminal's character encoding could change when connecting to different hosts. ### Shell Integration Required You must install [Shell Integration](documentation-shell-integration.html) on all machines and all user accounts where you plan to use Automatic Profile Switching (either by using the scripts or the Triggers workaround described in the Shell Integration docs). #### Rule Syntax In *Settings>Profiles>Advanced*, you may specify a set of rules. When any session satisfies a rule in a given profile, it will switch to that profile. Rules consist of three optional components: the user name, the hostname, and the path. At least one component must be present, since an empty rule is not allowed. The hostname is required only when both a user name and a path are specified. A user name is a unix accont name (e.g., *root*) followed by an `@`. A path always begins with a `/`. Any time a hostname is followed by a path, they are separated by a `:`. For example, `iterm2.com:/users/george`. It may include `*` wildcards. A hostname can be a DNS name, like `iterm2.com` or an IP address like `127.0.0.1`. A hostname may contain one or more `*` characters, which act as a wildcard (like globbing in Unix). The job name is the name of the executable. For example, "vim" or "bash". It must be prefixed with an ampersand `&`. For example, `&emacs*`. Starting with version 3.6, the rule is matched against the full command line rather than only the job name. Additionally, a rule may be designated as sticky by beginning with a `!`. This will be described below, in the *Automatic Reversion* section. Some examples: - `[[email protected]](https://iterm2.com/cdn-cgi/l/email-protection):/users/george` - `george@*:/users/george` - `*:/users/george` - `*.iterm2.com:/users/george` - `dev.*.com:/users/george` - `[[email protected]](https://iterm2.com/cdn-cgi/l/email-protection)` - `iterm2.com` - `george@` - `iterm2.com:/users/george` - `/users/george` - `/users/*` - `&vim` - `iterm2.com&vim` - `!iterm2.com` Because more than one rule may match at any given time, rules with higher quality matches prevail over those with lower-quality matches. Quality is determined by a rule's score, which is computed by summing the scores for its matching parts. In order for a rule to be considered, all of its parts that are specified must match the current state. The scoring is defined as: - An exact match for the hostname scores 16 points. - A partial match for the hostname using a wildcard scores 8 points. - A match on the job name (wildcard or not) scores 4 points. - A match on the user name scores 2 points. - An exact match on the path scores one point. - A partial match on the path using a wildcard scores zero points, but does count as a match for the rule. The highest scoring rule, if any, will be used and the session's profile will be switched. The UI tries to prevent you from entering the same rule in two different profiles, but if that does happen then one profile is chosen arbitrarily. ### Automatic Reversion After APS switches a session's profile, its rules may eventually cease to match (for example, the hostname changes back to "localhost" because an ssh session ends). If no profile has a matching rule, the session's original profile will be restored. The exception is if the last-matched rule was "sticky". A sticky rule is prefixed with an `!`. #### Implementation Each session maintains a stack of profiles. Initially, the stack contains the profile the session was created with. When the username, hostname, or path changes, iTerm2 finds the best-matching profile. If some profile has a matching rule, one of two things happens: - If that profile is already on the stack, profiles above that one will be removed from the stack and the session will switch to that profile. - Failing that, the profile will be pushed on the stack and the session will switch to that profile. If no profile has a matching rule, the stack is emptied (except for the first entry, the original profile for the session) and the session reverts to its original profile. Rules may begin with ! to indicate "stickiness". A sticky rule causes its profile to stay even after the rule no longer applies, so long as no other rule matches. ### Triggers Since it's impractical to install shell integration everywhere (for example, as *root*), there will be times when you need to write a trigger to detect the current username or hostname. Please see the *Triggers* section of [Shell Integration](https://iterm2.com/shell_integration.html) for details. ### Troubleshooting There are a few ways things can go wrong. Please see the [Why doesn't secure copy/automatic profile switching work?](https://gitlab.com/gnachman/iterm2/wikis/scp-not-connecting) document for help diagnosing and fixing these issues. --- # Source: https://iterm2.com/documentation-badges.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Badges A *badge* is a large text label that appears in the top right of a terminal session to provide dynamic status, such as the current host name or git branch. Its initial value is defined in **Settings>Profiles>General>Badge** and it can be changed by an iTerm2-proprietary escape sequence. This value is an [interpolated string](documentation-scripting-fundamentals.html), which means the badge can display the value of [variables](documentation-variables.html). Here is an example of a session with a badge indicating the current user and host name. * ### Escape Sequences The badge may be set with the following control sequence: ``` OSC 1337 ; SetBadgeFormat=Base-64 encoded badge format* ST ``` Here's an example that works in 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) ``` ### Color The badge's color may be set in *Settings>Profiles>Colors*. The font and size can be adjusted by selecting *Settings>Profiles>General>Edit…* next to the *Badge* field. --- # Source: https://iterm2.com/documentation-buried-sessions.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Buried Sessions A buried session is a session that continues to run but is not a part of any window. If you have a long-running job that you want out of the way, it can be convenient to bury its session. It is used by default for the session where you initiate a tmux integration client using [tmux Integration](https://iterm2.com/documentation-tmux-integration.html). To bury the current session, select **Session > Bury Session**. To restore a session, select it from the list of buried sessions in **Session > Buried Sessions**. --- # Source: https://iterm2.com/documentation-captured-output.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Captured Output iTerm2 has a feature called "Captured Output" which helps you find and track important lines of output from logs, build processes, and such. ### What does it do? Captured Output is a tool that may be added to iTerm2's toolbelt (a view on the right side of terminal windows). It works in conjunction with user-defined [Triggers](https://www.iterm2.com/triggers.html). A Trigger whose action is *Capture Output* looks for lines of output that match its regular expression. When one is found, the entire line is added to the Captured Output tool. When the user clicks on a line in the Captured Output tool, iTerm2 scrolls to reveal that line. Double-clicking on a line in the Captured Output tools run a user-defined [Coprocess](https://www.iterm2.com/coprocesses.html). ### Shell Integration Required [Shell Integration](https://www.iterm2.com/shell_integration.html) must be installed because Captured Output ties in to command history. Ensure you have enough scrollback history to contain the full output of your build command. The default of 1000 may not be sufficient. You can adjust this in **Prefs > Profiles > Terminal > Scrollback lines**. ### Example One way to use Captured Output is to view compiler output. Suppose you run *make* and get thousands of lines of output, some of which may contain errors or warnings. You'd like to examine each one and take some action on it. Here's how you would use Captured Output to assist with this task: #### Step 1: Create Triggers [Create a Trigger](https://iterm2.com/documentation-triggers.html) with the **Capture Output** action that matches your compiler's errors and warnings. Clang's errors look like this: ``` filename.c:54:9: error: use of undeclared identifier 'foo' ``` The following regular expression matches errors and warnings from Clang: ``` ^([_a-zA-Z0-9+/.-]+):([0-9]+):[0-9]+: (?:error|warning): ``` There are two capture groups defined. We'll come back to those later. #### Step 2: Open the Toolbelt Open the Toolbelt by selecting the menu item Toolbelt > Show Toolbelt. Enable the Toolbelt > Captured Output menu item to ensure it is visible. #### Step 3: Run make Kick off the build by running make. It spits out thousands of lines of output. #### Step 4: Examine the Captured Output tool Any errors or warnings that appear in the compiler output will appear in the Captured Output tool. Select an entry in the tool. iTerm2 scrolls to display the line and briefly highlights it in blue. #### Step 5: Open the file containing the error The Trigger created in step 1 takes an optional parameter. It is a command for iTerm2 to execute as a [Coprocess](https://www.iterm2.com/coprocesses.html) when you double-click an entry in the Captured Output tool. An example command is: ``` echo vim \1; sleep 0.5; echo \2G ``` This coprocess command assumes you are at the command line, and it enters a command to open the offending file to the line number with an error. This is where the capture groups in the regular expression from step 1 become useful. For example, if the filename was "filename.c" and the error was on line 20, as in this error message: ``` filename.c:20:9 error: use of undeclared identifier 'foo' ``` The coprocess would: - Type "vim filename.c", followed by enter, as though you were typing it at the keyboard. - Wait half a second. - Type "20G". #### Step 6: Check it off the list You can right-click on an entry in Captured Output to open a menu, which contains a single item: "Toggle Checkmark". This helps you remember which entries have been dealt with as you go through errors and warnings in your compiler output. ### Navigation Captured Output is linked to the Command History tool. If no command is selected in the Command History tool, then the most recent captured output is displayed. Otherwise, the captured output from the selected command is displayed. You can remove a selection from the Command History tool by cmd-clicking on it. ## Clearing Captured Output You can use the `ClearCapturedOutput` control sequence to remove captured output. This is useful to do before starting a compilation which may produce errors. Doing so ensures the only captured errors are from the most recent build. Use the following command in bash to produce the control sequence: `printf "\e]1337;ClearCapturedOutput\e\\"` --- # Source: https://iterm2.com/documentation-command-selection.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Command Selection and Command URLs Syntax If you have [Shell Integration](documentation-shell-integration.html) installed, you can click on a command or its output to select it. The selection is indicated by drawing a colored line around the command and its output. Other areas are dimmed. When a command is selected: - Search is restricted to the selected region. - Filtering is restricted to the selected region. - **Select All** is restricted to the selected region. - You can use Cmd-Up and Cmd-Down to navigate to the previous and next commands. Additionally, various buttons appear at the top right of the selected region: - An Info button, which opens the Command Info panel. This reveals information about the command such as how long it ran and its exit status and gives you controls to re-send, copy, share, and more. - A Share button, which opens a menu allowing you to save, copy, or share the command. - A bookmark button, which allows you to create a "named mark". You can find named marks under **Edit > Named Marks** or in the **Named Marks** tool in the toolbelt. This makes it easy to navigate back to a command later on. - A copy button, which lets you copy the command or its output. ### Disabling To disable command selection turn off **Settings > General > Selection > Clicking on a command selects it to restrict Find and Filter**. You can also select a command and click the settings button on the top right to open a menu that lets you disable the feature. ### Command URLs The share button introduces the concept of command URLs. Here is a simple example of a command URL: `iterm2:/command?c=date`. The scheme is always `iterm2` and the path is always `/command`. If a hostname is present, iTerm2 will attempt to ssh to the host to run the command. For exmaple, `iterm2:[[email protected]](https://iterm2.com/cdn-cgi/l/email-protection)/command?c=date` runs `date` on host `example.com` as user `gnachman`. The optional `d` query parameter gives a directory to change into prior to running the command. Normally when you open a command URL you are presented with a window that describes what will be done and offers options on how to run it (e.g., in a new tab, a new window, or in the current session). The optional `silent` query parameter suppresses this window. A confirmation dialog is shown instead. If the user consents, the command runs in the background and its output is not shown. This query parameter does not take a value. --- # Source: https://iterm2.com/documentation-coprocesses.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Coprocesses iTerm2 offers support for "coprocesses". This very powerful feature will allow you to interact with your terminal session in a new way. #### What is a Coprocess? A coprocess is a job, such as a shell script, that has a special relationship with a particular iTerm2 session. All output in a terminal window (that is, what you see on the screen) is also input to the coprocess. All output from the coprocess acts like text that the user is typing at the keyboard. One obvious use of this feature is to automate interaction. For instance, suppose you want to automate your presence in a chat room. The following script could be used as a coprocess: ``` #!/usr/bin/python import sys while True: line = raw_input() if line.strip() == "Are you there?": print "Yes" sys.stdout.flush() ``` You could disappear for years before your friends discover you're gone. #### How Do I Start a Coprocess? There are two ways to start a coprocess. - Select "Run Coprocess..." from the Session menu. Enter the name of a command to run as a coprocess. - Create a Trigger in Prefs>Profiles>Advanced and select Run Coprocess... as the action. Give the script to run as a parameter. Triggers also have Silent Coprocesses, which prevent any output from going to the screen. This is useful for ZModem, for example. #### Usage A session can not have more than one coprocess at a time. When a coprocess is active, an icon will indicate that in the top right of the session. #### Technical Details The coprocess's stdin is a byte-for-byte copy of the input from the session's pty, beginning at the time the coprocess starts. In the case of a trigger-started coprocess, the line of input that triggered it MAY be the first line of input to the coprocess, but this is not guaranteed. If a coprocess is running, triggers with a Run Coprocess action will not fire. The coprocess's stdout stream will be treated the same as keyboard input. A small amount of buffering is provided for both input and output of the coprocess. When a buffer fills, the coprocess will block. --- # Source: https://iterm2.com/documentation-copymode.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Copy Mode Copy Mode allows you to make selections using the keyboard. To enter or exit Copy Mode, select Edit > Copy Mode. You can also enter copy mode by pressing immediately after making a selection with the mouse. A special cursor rendered as a downward-pointing arrow is visible while in Copy Mode. While in Copy Mode, the session’s contents will not change. You can use the keyboard to move the cursor and modify the selection using these keystrokes: Changing Modes Keystroke Action Stop selecting , q, , Exit copy mode Toggle rectangular selection , v Toggle selection by character V Toggle selection by line Basic Movement Keystroke Action h, Move left j, Move down k, Move up l, Move right Content-Based Movement Keystroke Action , , , b Move back one word, treating symbols as word breaks. , , , w Move forward one word, treating symbols as word breaks. B Move back one word, treating symbols as part of a word. W Move forward one word, treating symbols as part of a word. [ Move to previous mark ] Move to next mark Screen Movement Keystroke Action , Move up one screen , Move down one screen H Move to top of visible area M Move to middle of visible area L Move to bottom of visible area Line Movement Keystroke Action ^, Move to start of indentation 0 Move to start of line $ Move to end of line Move to start of next line Document Movement Keystroke Action g Move to start G Move to end Other Commands Keystroke Action o Swap cursor and other selection endpoint , y Copy selection --- # Source: https://iterm2.com/documentation-dynamic-profiles.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Dynamic Profiles *Dynamic Profiles* is a feature that allows you to store your profiles in a file outside the usual macOS settings database. Profiles may be changed at runtime by editing one or more plist files (formatted as JSON, XML, or in binary). Changes are picked up immediately. ### Availability Dynamic Profiles are available in iTerm2 2.9.20140923 and later. ### Usage When iTerm2 starts, it creates a folder: ``` ~/Library/Application Support/iTerm2/DynamicProfiles ``` While iTerm2 runs, it monitors the contents of that folder. Any time the folder's contents change, all files in it are reloaded. Files in this folder are expected to be formatted as Apple [Property Lists](https://en.wikipedia.org/wiki/Property_list). No particular file extension is required. All files in the folder must be valid property lists. If any is malformed, then no changes will be processed. ### Property List Format A property list describes a data structure consisting of arrays, dictionaries, strings, integers, and boolean values. Property lists may be written in JSON or XML. Here's an example of the skeletal structure of a JSON property list that iTerm2 expects for Dynamic Profiles: ``` { "Profiles": [ { [attributes for the first profile go here] }, { [attributes for the second profile go here] }, [more profiles] ] } ``` There are two required fields for each profile: - Guid - Name The "Guid" is a globally unique identifier. It is used to track changes to the profile over time. No other profile should ever have the same guid. One easy way to generate a Guid is to use the *uuidgen* program, which comes standard with macOS. The "Name" is the name, as seen in the Profiles window or in Settings. Here is a fully formed (but minimal) Dynamic Profiles plist: ``` { "Profiles": [ { "Name": "Example", "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958" } ] } ``` ### Editing The only way to change a dynamic profile is to modify its parent profile or to modify the property list file. If you change its properties through the Settings UI those changes will *not* be reflected in the property list. ### Attributes Every profile preference that iTerm2 supports may be an attribute of a Dynamic Profile. Since there are dozens of attributes, you usually won't specify them all. Any attribute not specified will inherit its value from the default profile, or a specified "parent" profile (see below). The easiest way to find the name and legal value of a profile attribute is to copy it from a known-good reference. To get the JSON for a profile you already have, follow these steps: - Open Settings > Profiles - Select a profile - Open the *Other Actions* menu beneath the list of profiles - Select *Save Profile as JSON* - Open the file in your favorite editor. If you use this as the basis of a Dynamic Profile, remember to chantge the Guid. A Dynamic Profile with a Guid equal to an existing Guid of a regular profile will be ignored. #### Parent Profiles Normally, a dynamic profile inherits any attributes you don't explicitly specify from the default profile. You may also specify a particular profile to inherit from using the `Dynamic Profile Parent Name` attribute. The value it takes is a profile name (that is, the name you see listed in the list of profiles in Settings box). Profile names are not guaranteed to be unique, but they are more convenient than GUIDs. If no profile with the specified name is found, the default profile is used instead. For example: Starting in version 3.4.9, `Dynamic Profile Parent GUID` is another way to specify a parent. It takes precedence over `Dynamic Profile Parent Name`. ``` { "Profiles": [ { "Name": "Example", "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958", "Dynamic Profile Parent Name": "Light Background" } ] } ``` #### Rewritable You can mark a dynamic profile as "rewritable" which means iTerm2 can make changes to the file on disk to reflect changes made in the settings UI. Simply add `"Rewritable": true` to your profile to enable rewritability. ### Minutiae Dynamic profiles are loaded in alphabetical order by filename. Within a particular file, they are loaded in the order they're listed in. This only matters if one dynamic profile references another dynamic profile as its parent; the parent should be placed so it loads before any of its children. For all other purposes, the filenames don't matter. The *Dynamic* will automatically be added to all Dynamic Profiles. ### Troubleshooting If something goes wrong loading a Dynamic Profile, errors will be logged to Console.app. ### Triggers By default, *Highlight* triggers save colors in a large inscrutable mess of a format. For dynamic profiles, you can use `{#rrggbb,#rrggbb}` in place of the large inscrutable mess. The first value gives the foreground color and the second value gives the background color. Replace either `#rrggbb` with an empty string to not change that color. For example, to make the foreground red without changing the background use `#{ff0000,}`. ### Example Here's an example for a common use case: a list of profiles for *ssh*ing to various hosts. In this example, I've used the hostname as the Guid, which makes constructing this file a little easier and works well enough. ``` { "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", }, ] } ``` --- # Source: https://iterm2.com/documentation-escape-codes.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Proprietary Escape Codes iTerm2 supports several non-standard escape codes. These may not work properly in tmux or screen, and may have unknown effects on other terminal emulators. Proceed with caution. The control sequences use the following notation: - `ESC` means "Escape" (hex code 0x1b) . - `ST` means either `BEL` (hex code 0x07) or `ESC \\`. - Spaces in control sequences are to be ignored. - Values in [brackets] are variable parameters, not literals. - `OSC` means `ESC ]` - `CSI` means `ESC [` - `SP` means a literal "space" character (not ignored!) The OSC command `50` used to be used but it conflicts with xterm, so it is now `1337`. #### Report Foreground/Background Colors (OSC 4) The xterm-defined OSC 4 control sequence has a mode where it reports the RGB value of a color. iTerm2 extends its reporting mode to add two additional color indices representing the default foreground and background color. To get the background color: ``` OSC 4 ; -2; ? ST ``` And this gets the foreground color: ``` OSC 4 ; -1 ; ? ST ``` For background and foreground respectively, the terminal will write back: ``` OSC 4 ; -2 ; rgb : [red] / [green] / [blue] ST OSC 4 ; -1 ; rgb : [red] / [green] / [blue] ST ``` Where `[red]`, `[green]`, and `[blue]` are either 2 or 4-digit hex values like `14a7` or `ff`. For 4-digit values, you can get an approximation of the 2-digit value by taking the first two digits. #### Anchor (OSC 8) VTE and iTerm2 support OSC 8 for defining hyperlinks, much like HTML's anchor tag. ``` OSC 8 ; [params] ; [url] ST ``` `[params]` consists of zero or more colon-delimited key-value pairs. A key-value pair is formatted as **key=value**. The only currently defined key is **id**. Two adjacent hyperlinks with the same URL but different **id**s will highlight separately when Command is pressed during hover. If the **url** is absent then that ends the hyperlink. Typical usage would look like: ``` OSC 8 ; ; https://example.com/ ST Link to example website OSC 8 ; ; ST ``` To open a link, hold Command and click the link. Note: in iTerm2 version 3.4 and later, if the URL has the `file` scheme and a `#` fragment is present then the semantic history rules will apply for opening the file. It may optionally include a line number, like `file:///tmp/file.txt#123` or line number and column number like `file:///tmp/file.txt#123:45`. #### Set cursor shape ``` OSC 1337 ; CursorShape=[N] ST ``` where `[N]`=0, 1, or 2. - 0: Block - 1: Vertical bar - 2: Underline Add this to your `.vimrc` to change cursor shape in insert mode: ``` let &t_SI = "\]1337;CursorShape=1\x7" let &t_EI = "\]1337;CursorShape=0\x7" ``` This is derived from [Konsole](https://vim.wikia.com/wiki/Change_cursor_shape_in_different_modes). #### Set Mark The "Set Mark" (cmd-shift-M) command allows you to record a location and then jump back to it later (with cmd-shift-J). The following escape code has the same effect as that command: ``` OSC 1337 ; SetMark ST ``` #### Steal Focus To bring iTerm2 to the foreground: ``` OSC 1337 ; StealFocus ST ``` #### Clear Scrollback History To erase the scrollback history: ``` OSC 1337 ; ClearScrollback ST ``` #### Set current directory To inform iTerm2 of the current directory to help semantic history: ``` OSC 1337 ; CurrentDir=[current directory] ST ``` #### Post a notification To post a notification: ``` OSC 9 ; [Message content goes here] ST ``` #### Change profile To change the session's profile on the fly: ``` OSC 1337 SetProfile=[new profile name] ST ``` #### Copy to clipboard To place text in the pasteboard: ``` OSC 1337 ; CopyToClipboard=[clipboard name] ST ``` Where name is one of "rule", "find", "font", or empty to mean the general pasteboard (which is what you normally want). After this is sent, all text received is placed in the pasteboard until this code comes in: ``` OSC 1337 ; EndCopy ST ``` #### Set window title and tab chrome background color To set the window title and tab color use this escape sequence: ``` OSC 6 ; 1 ; bg ; red ; brightness ; [N] ST OSC 6 ; 1 ; bg ; green ; brightness ; [N] ST OSC 6 ; 1 ; bg ; blue ; brightness ; [N] ST ``` Replace `[N]` with a decimal value in 0 to 255. Example in bash that turns the background purple: ``` echo -e "\033]6;1;bg;red;brightness;255\a" echo -e "\033]6;1;bg;green;brightness;0\a" echo -e "\033]6;1;bg;blue;brightness;255\a" ``` To reset the window title and tab color, use this code: ``` OSC 6 ; 1 ; bg ; * ; default ST ``` For example: ``` echo -e "\033]6;1;bg;*;default\a" ``` #### Change the color palette To change the current session's colors use this code: ``` OSC 1337 ; SetColors=[key]=[value] ST ``` `[key]` gives the color to change. The accepted values are: fg bg bold link selbg selfg curbg curfg underline tab" black red green yellow blue magenta cyan white br_black br_red br_green br_yellow br_blue br_magenta br_cyan br_white `[value]` gives the new color. The following formats are accepted: - RGB (three hex digits, like `fff`) - RRGGBB (six hex digits, like `f0f0f0`) - cs:RGB (like RGB but `cs` gives a color space) - cs:RRGGBB (like RRGGBB but `cs` gives a color space) If a color space is given, it should be one of: - srgb (the standard sRGB color space) - rgb (the device-specific color space) - p3 (the standard P3 color space, whose gamut is supported on some newer hardware) The following alternate schemes are also supported: * If `key` is `preset` then `value` should be the name of a color preset. * If `key` is `tab` then a value of `default` removes the tab color and restores it to the system default. A second escape sequence is also supported, but its use is not recommended: ``` OSC P [n] [rr] [gg] [bb] ST ``` Replace `[n]` with: - `0`-`f` (hex) = ansi color - `g` = foreground - `h` = background - `i` = bold color - `j` = selection color - `k` = selected text color - `l` = cursor - `m` = cursor text `[rr]`, `[gg]`, `[bb]` are 2-digit hex value (for example, "ff"). Example in bash that changes the foreground color blue: ``` echo -e "\033]Pg4040ff\033\\" ``` #### Annotations To add an annotation use on of these sequences: ``` OSC 1337 ; AddAnnotation=[message] ST OSC 1337 ; AddAnnotation=[length] | [message] ST OSC 1337 ; AddAnnotation=[message] | [length] | [x-coord] | [y-coord] ST OSC 1337 ; AddHiddenAnnotation=[message] ST OSC 1337 ; AddHiddenAnnotation=[length] | [message] ST OSC 1337 ; AddHiddenAnnotation=[message] | [length] | [x-coord] | [y-coord] ST ``` - `[message]`: The message to attach to the annotation. - `[length]`: The number of cells to annotate. Defaults to the rest of the line beginning at the start of the annotation. - `[x-coord]` and `[y-coord]`: The starting coordinate for the annotation. Defaults to the cursor's coordinate. *AddHiddenAnnotation* does not reveal the annotation window at the time the escape sequence is received, while *AddAnnotation* opens it immediately. #### Cursor Guide ``` OSC 1337 ; HighlightCursorLine=[boolean] ST ``` The `[boolean]` should be `yes` or `no`. This shows or hides the cursor guide. #### Attention ``` OSC 1337 ; RequestAttention=[value] ST ``` The `[value]` should be `yes` to request attention by bouncing the dock icon indefinitely, `once` to bounce it a single time, or `no` to cancel a previous request. If it is `fireworks` then fireworks explode at the cursor's location. #### Background Image ``` OSC 1337 ; SetBackgroundImageFile=[base64] ST ``` The value of `[base64]` is a base64-encoded filename to display as a background image. If it is an empty string then the background image will be removed. User confirmation is required as a security measure. #### Report Cell Size ``` OSC 1337 ; ReportCellSize ST ``` The terminal responds with either: ``` OSC 1337 ; ReportCellSize=[height];[width] ST ``` Or, in newer versions: ``` OSC 1337 ; ReportCellSize=[height];[width];[scale] ST ``` `[scale]` gives the number of pixels (physical units) to points (logical units). 1.0 means non-retina, 2.0 means retina. It could take other values in the future. `[height]` and `[width]` are floating point values giving the size in points of a single character cell. For example: ``` OSC 1337 ; ReportCellSize=17.50;8.00;2.0 ST ``` #### Copy to Pasteboard You can place a string in the system's pasteboard with this sequence: ``` OSC 1337 ; Copy=:[base64] ST ``` Where `[base64]` is the base64-encoded string to copy to the pasteboard. #### Report Variable Each iTerm2 session has internal variables (as described in [Scripting Fundamentals](documentation-scripting-fundamentals.html)). This escape sequence reports a variable's value: ``` OSC 1337 ; ReportVariable=[base64] ST ``` Where `[base64]` is a base64-encoded variable name, like `session.name`. It responds with: ``` OSC 1337 ; ReportVariable=[base64] ST ``` Where `[base64]` is a base64-encoded value. #### Badge The badge has custom escape sequences described [here](documentation-badges.html). #### Downloads For information on file downloads and inline images, see [here](documentation-images.html). #### Uploads To request the user select one or more files to upload, send: ``` OSC 1337 ; RequestUpload=format=[type] ST ``` In the future the `[type]` may be configurable, but for now it must always be `tgz`, which is a tar and gzipped file. When iTerm2 receives this it will respond with a status of `ok` or `abort` followed by a newline. If the status is `ok` then it will be followed by a base-64 encoded tar.gz file. If the user selects multiple files they will be placed in a directory within the tar file. #### Set Touch Bar Key Labels You can configure touch bar key labels for function keys and for the "status" button. The code used is: ``` OSC 1337 ; SetKeyLabel=[key]=[value] ST ``` Where `[key]` is one of `F1`, `F2`, ..., `F24`, to adjust a function key label; or it can be `status` to adjust the touch bar status button. You can also save and restore sets of key labels using a stack. To push the current key labels on the stack use: ``` OSC 1337 ; PushKeyLabels ST ``` To pop them: ``` OSC 1337 ; PopKeyLabels ST ``` You can optionally label the entry in the stack when you push so that pop will pop multiple sets of key labels if needed. This is useful if a program crashes or an ssh session exits unexpectedly. The corresponding codes with labels are: ``` OSC 1337 ; PushKeyLabels=[label] ST OSC 1337 ; PopKeyLabels=[label] ST ``` Where `[label]` is an ASCII string that works best if it is unique in the stack. #### Unicode Version iTerm2 by default uses Unicode 9's width tables. The user can opt to use Unicode 8's tables with a preference (for backward compatibility with older locale databases). Since not all apps will be updated at the same time, you can tell iTerm2 to use a particular set of width tables with: ``` OSC 1337 ; UnicodeVersion=[n] ST ``` Where `[n]` is 8 or 9 You can push the current value on a stack and pop it off to return to the previous value by setting `n` to `push` or `pop`. Optionally, you may affix a label after `push` by setting `n` to something like `push mylabel`. This attaches a label to that stack entry. When you pop the same label, entries will be popped until that one is found. Set `n` to `pop mylabel` to effect this. This is useful if a program crashes or an ssh session ends unexpectedly. #### File Transfer OSC 1337 ; File=[args] ST See [Images](documentation-images.html) for details. Note that if the file is not an image but would benefit from native rendering, you can use this control sequence to display it with syntax highlighting and proporitonally spaced typograhy. For example, this is a good way to view a markdown file. In that case, the following optional arguments may be provided: - `type=` *mime type or extension* - `mode=` `regular` or `wide` When you pass `mode=wide` then horizontal scrolling will be allowed for the contents of the document. #### Custom Control Sequences iTerm2 allows scripts to define custom control sequences. See the [Create Window](https://iterm2.com/python-api/examples/create_window.html) example for a working demo. The control sequence is: ``` OSC 1337 ; Custom=id=[secret]:[pattern] ST ``` Where `[secret]` is a secret shared between the script implementing the control sequence and the program producing it, as a security measure to make it more difficult for untrusted text to invoke a custom control sequence. `[pattern]` is used to identify the sequence and may contain any parameters the script needs to handle it. ## Shell Integration/FinalTerm iTerm2's [Shell Integration](documentation-shell-integration.html) feature is made possible by proprietary escape sequences pioneered by the FinalTerm emulator. FinalTerm is defunct, but the escape sequences are documented here. ### Concepts The goal of the FinalTerm escape sequences is to mark up a shell's output with semantic information about where the prompt begins, where the user-entered command begins, and where the command's output begins and ends. **[PROMPT]**prompt% **[COMMAND_START]** ls -l **[COMMAND_EXECUTED]** -rw-r--r-- 1 user group 127 May 1 2016 filename **[COMMAND_FINISHED]** ### Escape Sequences FinalTerm originally defined various escape sequences in its original spec that are not supported by iTerm2 and are not described in this document. The best remaining references to these codes are in iTerm2's source code. #### FTCS_PROMPT ``` OSC 133 ; A ST ``` Sent just before start of shell prompt. #### FTCS_COMMAND_START ``` OSC 133 ; B ST ``` Sent just after end of shell prompt, before the user-entered command. #### FTCS_COMMAND_EXECUTED ``` OSC 133 ; C ST ``` Sent just before start of command output. All text between `FTCS_COMMAND_START` and `FTCS_COMMAND_EXECUTED` at the time `FTCS_COMMAND_EXECUTED` is received excluding terminal whitespace is considered the command the user entered. It is expected that user-entered commands will be edited interactively, so the screen contents are captured without regard to how they came to contain their state. If the cursor's location is before (above, or if on the same line, left of) its location when `FTCS_COMMAND_START` was received, then the command will be treated as the empty string. #### FTCS_COMMAND_FINISHED ``` OSC 133 ; D ; [Ps] ST OSC 133 ; D ST ``` The interpretation of this command depends on which `FTCS` was most recently received prior to `FTCS_COMMAND_FINISHED`. This command may be sent after `FTCS_COMMAND_START` to indicate that a command was aborted. All state associated with the preceding prompt and the command until its receipt will be deleted. Either form is accepted for an abort. If the `[Ps]` argument is provided to an abort it will be ignored. If this command is sent after `FTCS_COMMAND_EXECUTED`, then it indicates the end of command prompt. Only the first form with `[Ps]` should be used in this case. `[Ps]` is the command's exit status, a number in the range 0-255 represented as one or more ASCII decimal digits. A status of 0 is considered "success" and nonzero indicates "failure." The terminal may choose to indicate this visually. If neither `FTCS_COMMAND_START` nor `FTCS_COMMAND_EXECUTED` was sent prior to `FTCS_COMMAND_FINISHED` it should be ignored. ### iTerm2 Extensions iTerm2 extends FinalTerm's suite of escape sequences. #### SetUserVar ``` OSC 1337 ; SetUserVar=[Ps1]=[Ps2] ST ``` Sets the value of a user-defined variable. iTerm2 keeps a dictionary of key-value pairs which may be used within iTerm2 as string substitutions. See [Scripting Fundamentals](documentation-scripting-fundamentals.html) for more information on variables and how they can be used. `[Ps1]` is the key. `[Ps2]` is the base64-encoded value. #### ShellIntegrationVersion Two forms are accepted. The second form is deprecated and should not be used: ``` OSC 1337 ; ShellIntegrationVersion=[Pn] ; [Ps] ST OSC 1337 ; ShellIntegrationVersion=[Pn] ST ``` Reports the current version of the shell integration script. `[Pn]` is the version. `[Ps]` is the name of the shell (e.g., `bash`). iTerm2 has a baked-in notion of the "current" version and if it sees a lower number the user will be prompted to upgrade. The version number is specific to the shell. #### RemoteHost ``` OSC 1337 ; RemoteHost=[Ps1]@[Ps2] ST ``` Reports the user name and hostname. `[Ps1]` is username. `[Ps2]` is fully-qualified hostname. The following synonym is available as a combination of RemoteHost and CurrentDir: ``` OSC 7 [Ps] ST ``` where `[Ps]` is a file URL with a hostname and a path, like `file://example.com/usr/bin`. #### CurrentDir ``` OSC 1337 ; CurrentDir=[Ps1] ST ``` Reports the current directory. `[PS1]` is the current directory. The following synonym is available as a combination of RemoteHost and CurrentDir: ``` OSC 7 ; [Ps] ST ``` where `[Ps]` is a file URL with a hostname and a path, like `file://example.com/usr/bin`. #### ClearCapturedOutput ``` OSC 1337 ; ClearCapturedOutput ST ``` Erases the current captured output. #### DECSCUSR 0 ``` CSI 0 SP q ``` This will reset the cursor to its default appearance. This is an intentional deviation from the behavior of DEC virtual terminals. #### Curly Underlines ``` CSI 4 : 3 m ``` This turns on curly underlines. #### Extended Device Attributes Report terminal name and version. ``` CSI > q ``` iTerm2 will respond with: ``` ESC P > | iTerm2 [version] ST ``` Where [version] is the version of iTerm2, such as `3.4.0`. #### Open URL To request that iTerm2 open a URL: ``` OSC 1337 ; OpenURL=: [url] ST ``` Where [url] is a base64-encoded URL. The user must grant permission, and the feature can also be disabled. #### Disinter To disinter a buried session, send: ``` OSC 1337 ; Disinter ST ``` #### Blocks To define a region as a code block: ``` OSC 1337 ; Block=id=[identifier] ; attr=start|end ``` Use attr=start to begin a block and attr=end to end it, Use the same identifier for both. #### Buttons To create a copy button that, when clicked, copies a code block: ``` OSC 1337 ; Button=type=copy ; block=[identifier] ``` The `identifier` should reference the identifier of a clode block defined with `OSC 1337;Block=...`. #### Feature Reporting To detect which features the terminal supports, use the protocol described in [feature reporting](https://iterm2.com/feature-reporting/). --- # Source: https://iterm2.com/faq.html #### Q: What operating systems are supported? A: iTerm2 is for macOS only. See the downloads page for which OS versions are supported by each version of the app. #### Q: I don't like the way that iTerm2 renders bold fonts. A: Go to Preferences->Profiles->Text and change the "Draw bold text in bold font" and "Draw bold text in bright colors" settings. Try running this command in bash to see the difference between the two behaviors: ``` printf '\e[0;31mplain\n\e[1;31mbold\n'\ '\e[0;91mhighlight\n\e[1;91mbold+highlight\n\e[0m' ``` #### Q: How can I improve iTerm2's performance? A: Make sure you are running the latest version. Disable transparency and blur. Use a solid background color rather than an image. If you are on 3.2 or later, ensure the GPU renderer is enabled and that it can be used per the restrictions described at [Metal Renderer](https://gitlab.com/gnachman/iterm2/wikis/Metal-Renderer). #### Q: Why my arrow/HOME/END keys are not working? A: Check that the `$TERM` variable is correct. `xterm-256color` is recommended. `xterm-new` will also work. Make sure you do not have custom key bindings in **Preferences > Keys** or **Preferences > Profiles > Keys** for these keys. Disabling **Preferences > Profiles > Keys > Allow application keypad mode** will prevent your terminal from getting stuck in application keypad mode, which often has the effect of breaking keys that normally work. #### Q: Where does iTerm2 store its settings? A: Preferences, including profiles, are stored in ~/Library/Preferences/com.googlecode.iterm2.plist. To modify it, use the "defaults" command. For example, to delete all settings, run: ``` defaults delete com.googlecode.iterm2 ``` #### Q: The fonts are looking weird. What should I do? A: iTerm2 lets you to specify two fonts. If you only use English or western european languages, you probably only need to set the font for ASCII characters. For other languages, you need to specify a font that works with your language as the Non-ASCII font. You need to make sure the size (height) of two fonts do not differ greatly, so iTerm2 won't display a mess of mixed glyphs. #### Q: Some characters appear to be twice as wide as others, and things aren't lining up correctly. #### Q: I'm a Chinese, Japanese, or Korean user and some characters don't line up because they are not rendered in double-width. A: Go to **Preferences > Profiles > Text** and change the setting of "Treat ambiguous-width characters as double-width." #### Q: Why can't I set my session's shortcut key to Ctrl-Cmd-D? A: That key is used by macOS's Dictionary program. #### Q: How do I make the option/alt key act like Meta or send escape codes? A: Go to **Preferences > Profiles** tab. Select your profile on the left, and then open the Keyboard tab. At the bottom is a set of buttons that lets you select the behavior of the Option key. For most users, *Esc+* will be the best choice. #### Q: What modifier keys affect marking a selection for copy and paste? A: If you hold down modifier keys while making a selection, the behavior changes in various ways: - Alt/Option: Mouse reporting will be disabled. If you're using vim and you can't make a selection, try holding down the alt key and see if that fixes it. - Alt + Cmd: Make a rectangular selection. - Shift: Extend an existing selection. - Alt + Shift: Extend a rectangular selection. - Cmd: Make a discontinuous selection Additionally, you can affect other mouse-related activities with modifier keys: - Dragging a selection copies and pastes it. If you keep doing this by accident, turn on **Preferences > Advanced > To drag images or selected text, you must hold ⌘. This prevents accidental drags.**. - Cmd+click on a URL opens it. #### Q: How do I change a tab's title? A: Press Cmd-I (or View->Edit Current Session...) and enter a new title in the "Name" field. You can set it programmatically (in bash) with: ``` echo -e "\033];MY_NEW_TITLE\007" ``` #### Q: How do I set iTerm2 as the handler for ssh:// links? A: Two steps: - Create a new profile called "ssh". In the General tab, select the Command: button and enter $$ as the command. - In Preferences->Profiles->General, select "ssh" for "Select URL Schemes...." #### Q: How can I open a profile from the Profiles window in a new window without using the mouse? A: Select a profile with the up and down arrow keys and press shift-enter. #### Q: How do I get 256 color mode working in vim? A: The recommended way is to set your terminal type to xterm-256color in **Preferences > Profiles > Terminal > Report Terminal Type**. You may also need to put set background=light or set background=dark in your .vimrc. #### Q: Mouse reporting in vim doesn't work for some rows/columns in a big terminal window. A: Older mouse reporting protocols didn't work in large terminals. Recent versions of vim (at least 7.4) support the "SGR" protocol, which does not have any practical limits on terminal size. To enable it in vim, add this to your .vimrc: ``` if has('mouse_sgr') set ttymouse=sgr endif ``` #### Q: How do I post notifications from the command line? A: In bash: ``` echo $'\e]9;Notification Text\007' ``` #### Q: How do I make the mouse work in emacs? A: This is the simple but dumb way: ``` (require 'mwheel) (require 'mouse) (xterm-mouse-mode t) (mouse-wheel-mode t) (global-set-key [mouse-4] 'next-line) (global-set-key [mouse-5] 'previous-line) ``` [The rabbit hole goes deep.](https://www.emacswiki.org/emacs/SmoothScrolling) #### Q: Why is my text all black and white? A: The most common cause is that "minimum contrast" (under **Preferences > Profiles > Colors**) is turned up all the way. #### Q: How can I make the tab bar visible in fullscreen mode? A: Toggle Show Tabs in Fullscreen under the View menu (cmd-shift-T). #### Q: When I use a third-party app like SizeUp, Spectacle to make an iTerm2 window fill the screen it doesn't quite fill it. #### Q: When I use Magnet to move iTerm2 windows they do unexpected things (like not moving where I told them to). A: This is a side-effect of making the window size a multiple of the size of a single character's cell. Turn on **Preferences > Advanced > Terminal windows resize smoothly** to disable this behavior and that usually fixes the issue. #### Q: Where is the source code? A: [See gnachman's Github iTerm2 project.](https://github.com/gnachman/iTerm2) #### Q: How can I open iTerm2 to a directory from Finder? A: Right-click on the directory and select **Services > New iTerm2 Tab Here**. #### Q: How can I keep the cursor guide always visible? A: Turn on the **Cursor Guide** checkbox in **Preferences>Profiles>Colors**. #### Q: How can I make the toolbelt open automatically? A: Turn on the **Open Toolbelt** checkbox in **Preferences>Profiles>Window**. #### Q: How can I prevent the window from resizing when I change the font with cmd-+ and cmd--? A: Turn off **Preferences>General>Adjust window when changing font size**. #### Q: tmux integeration and mosh don't play nice together A: mosh is not a reliable transport. You have a few options if ssh is driving you nuts: - Use a [hacked version of mosh](https://github.com/4ast/mosh/) that is a reliable transport. Instructions on building it can be found [on Donn Lee's home page](http://donnlee.com/2018/03/31/mosh-with-iterm2s-tmux-integration/). - Use [Eternal Terminal](https://mistertea.github.io/EternalTerminal/). #### Q: The "Download with scp" context menu item does not work A: Did you install shell integration on the remote host? It's necessary to know what the hostname and user name are. If that doesn't fix it, you might need to give it a hint about which port or hostname to use. See [SCP not connecting](https://gitlab.com/gnachman/iterm2/wikis/scp-not-connecting) for more. #### Q: The keyboard shortcuts for find next/previous and for toggle full screen are not standard. How can I fix it? A: Next and previous are intentionally inverted to make typical use more convenient. Toggle full screen is not cmd-ctrl-F because all cmd-ctrl shortcuts are reserved because they can be bound to opening a profile. This predates the existence of full screen in macOS. You can change any shortcut in **Prefs > Keys**. The actions in question are **Find Again Up**, **Find Again Down**, and **Toggle Fullscreen**. #### Q: When I paste I get funny characters before and after the pasted text, like `0~` and `1~`. A: Paste bracketing was incorrectly left turned on. Paste bracketing is a feature that can be enabled by an application (such as vim or emacs) that causes the terminal emulator to put a control sequence before and after the pasted text. This allows a program like a text editor not to auto-indent pasted text, since it might already contain indents. Paste bracketing is turned on or off by a control sequence. If the application crashes or an ssh connection is lost, then paste bracketing will be left turned on. The next time you paste, the application receiving the text does not expect paste bracketing to be on (since it did not enable it) and you get this gibberish. You can disable paste bracketing by resetting the terminal. Select the menu item **Session > Reset**. If you install [Shell Integration](https://iterm2.com/shell_integration.html) on both your computer and the machine you ssh to, then iTerm2 can automatically detect when an ssh connection ends and paste bracketing is stuck "on", and automatically turn it off for you. #### Q: I can no longer change panes/tabs/windows with modifier + number. A: Turn on **Prefs > Keys > Emulate US Keyboard.** This change was made because some people were unable to type symbol characters that required a modifier + a key where a digit resides on a US keyboard, so the default was changed to not assume that the top row of keys were numeric. #### Q: Why can't I scroll with a Logitech mouse? A: Their drivers have a bug. Turn off the menu item **iTerm2 > Secure Keyboard Entry**. Complain to Logitech that their drivers are bad, or buy a mouse from a better brand. #### Q: I use bash and sometimes my prompt draws incorrectly. A: If you have problems where doing a reverse search or wrapping a long command causes letters to appear in the wrong place it may be because you have non-printing characters in your PS1. Place them between `\[` and `\]`. More info [here](https://www.tldp.org/HOWTO/Bash-Prompt-HOWTO/nonprintingchars.html). #### Q: What is "CSI u mode"? A: This is a way of reporting keystrokes which is mostly backwards compatible but enables more combinations of keys and modifiers to be properly reported. For example, it standardizes how option+arrow key works. Neovim has support out of the box. [Emacs can be persuaded to work by adding this to your `.emacs`.](https://gist.github.com/gnachman/b4fb1e643e7e82a546bc9f86f30360e4) #### Q: When I use `open` the app's window doesn't come to the foreground. A: This is a security feature of macOS when Secure Keyboard Entry is enabled. It prevents an app from stealing keyboard focus while you're entering sensitive text. Disable the menu item **iTerm2 > Secure Keyboard Entry** to resolve the issue. --- # Source: https://iterm2.com/features.html iTerm2 has a lot of features. Every conceivable desire a terminal user might have has been foreseen and solved. And these are just the main attractions! ### Split Panes Divide a tab up into multiple panes, each one showing a different session. You can slice vertically and horizontally and create any number of panes in any imaginable arrangement. Notice how inactive panes are slightly dimmed so it's easy to see which is active. ### Hotkey Window Register a hotkey that brings iTerm2 to the foreground when you're in another application. A terminal is always a keypress away. You can choose to have the hotkey open a dedicated window. This gives you an always-available terminal (like Visor, Guake, or Yakuake) at your fingertips. ### Search iTerm2 comes with a robust find-on-page feature. The UI stays out of the way. All matches are immediately highlighted. Even regular expression support is offered! ### Autocomplete Just type the start of any word that has ever appeared in your window and then Cmd-; will pop open a window with suggestions. The word you're looking for is usually on top of the list! ### Copy Mode Use the keyboard to make and modify selections. ### Paste History Paste history lets you revisit recently copied or pasted text. You can even opt to have the history saved to disk so it will never be lost. ### Instant Replay Instant replay lets you travel back in time to recover text that was erased from the terminal. ### Configurability A mind-boggling number of options lets you configure the terminal to suit you perfectly. Scroll horizontally to see more… ### Unixyness Coming from a Unix world? You'll feel at home with focus follows mouse, copy on select, middle button paste, and keyboard shortcuts to avoid mousing. ### 24-bit Color With both 24-bit and 256-color mode, Vim explodes with photorealism: the terminal is a medley of color and code comes alive. ### Readability Do you lose your cursor when there are lots of different colors or have programs display hard-to-read color combinations? With the Smart Cursor Color and Minimum Contrast features, you can ensure that these problems are gone for good. ### Mouse Reporting You can use the mouse to position the cursor, highlight text, and perform other functions in programs like Vim and Emacs with the mouse reporting feature. ### Notification Center Support You can choose to receive notifications of activity, bells, job completion, and more. Feel free to let a long job run in the background, secure in the knowledge that you'll know when it's done. ### Global Search Search all your tabs at once with Global Search. ### Tagged Profiles Do you need to store separate configurations for many different hosts? iTerm2 provides a taggable and searchable profiles database so you can easily find the profile you're looking for. ### Multi-Lingual iTerm2 features excellent internationalization support, including support for Unicode combining marks, full-width characters, Emoji, and many other Unicode features. ### Triggers iTerm2 supports user-defined triggers, which are actions that run when text matching a regular expression is received. You can use it to highlight words, automatically respond to prompts, notify you when something important happens, and more. ### Smart Selection iTerm2 can perform "smart selection" to highlight URLs, email addresses, filenames, and more by recognizing what is under the cursor and choosing how much text to select. ### Shell Integration iTerm2 can integrate with your shell so it knows where your shell prompt is, what commands you're entering, which host you are on, and what your current directory is. This enables all sorts of cool features: you can easily navigate to previous shell prompts with ⇧⌘↑ and ⇧⌘↓. Your most used directories will be remembered for you. You can auto-complete previously used commands. And much more! ### Automatic Profile Switching Using the Shell Integration feature, you can have iTerm2 switch profiles depending on what you're doing. For example, you can define a profile that's always used when you ssh to some hostname. Or when your username is root. Or even when you're in a particular directory. ### Inline Images iTerm2 has a custom escape sequence to display images right in the terminal. Even animated GIFs! ### Timestamps You can see the last-modified time of every line in the terminal. It's useful to know how long a job took to complete, if the data you're looking at is fresh, or to try to piece together what you were doing before leaving for the weekend. ### Password Manager Do you find yourself typing your password over and over again? Do you need to remember a bunch of passwords? Use iTerm2's built-in password manager. It stores your data securely encrypted in macOS's keychain, protected by your user account's password. iTerm2 includes a safety mechanism that ensures your password only gets entered at a password prompt. ### Advanced Paste With the Advanced Paste feature you can edit text before pasting it, convert it to base64, transform special characters, and more. ### Annotations You can select text in your terminal and add an *annotation* to it in iTerm2. If you're puzzling through a big log file, it's useful to mark it up with what you've learned. Working through a disassembly? Make notes about what each register does. Free your mind! ### Badges You can put a *badge* in the top right of your terminal showing information about the current session. It can show your username, hostname, or even custom data like the current git branch. ### Captured Output Use iTerm2 as your IDE. When you build a big project, you used to have to pore over its output to find warnings and errors. No more! With the *captured output* feature, iTerm2 finds those messages (based on regular expressions you define) and shows them in the toolbelt. You can navigate right to each message. A double-click will run a coprocess of your choice, which can (for example) open the file in your favorite editor right to the line with the error. --- # Source: https://iterm2.com/documentation-fonts.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Fonts While iTerm2 does not require monospaced fonts, they look much better than proportionately spaced fonts. iTerm2 has the capability of rendering text with thin strokes to improve readability. You can change how this works in the **Text** panel of the **Profiles** tab of **Settings**. You can also specify a "non-ASCII" font in the **Text** panel of profile Settings. This font will be used for all code points greater than or equal to 128 or for characters with combining marks. Some fonts, such as FiraCode, support ligatures if enabled in iTerm2. You can enable ligatures in **Prefs > Profiles > Text**. Ligatures are rendered using CoreText, which is significantly slower than Core Graphics. **NOTE:** Ligatures are not supported by the GPU renderer and will reduce performance. --- # Source: https://iterm2.com/documentation-general-usage.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # General Usage #### Tabs When you first start iTerm2, a window opens showing a terminal session. If you want to open more that one session at a time, you have a few options: You can create a new window (Shell > New Window), you can create a new tab (Shell > New Tab), or you can split the current session into two panes (Shell > Split Horizontally, Shell > Split Vertically), each of which is a separate session. Tabs in iTerm2 behave like tabs in other programs, most notably web browsers like Safari, Firefox, and Google Chrome. Note that you can drag and drop tabs to reorder them within a window. You can drag tabs from one window to another, and you can drag a tab from a window into a new window by dropping it outside any iTerm2 window's tab bar. By default, the label of each tab is the name of the job that's running in that session. Some systems are configured to augment this with additional information such as the hostname you're logged in to or your current directory (this is done by sending a special code of ESC]0;string ^G). Tab labels have indicators that tell you their status. A blue dot means new input was received. An activity indicator means new output is being received. When the session ends, a ⃠ icon appears in the tab. You can customize these indicators in Settings > Appearance. #### Edit Current Session The *Edit Current Session* panel lets you modify the appearance of a single session. If you customize some attribute of the session (for example, by changing the default text color) then subsequent changes to that same attribute in the profile will not affect the customized session. However, changes to other attributes of the profile will affect the customized session. #### Pointer The primary use of the mouse in iTerm2 is to select text, and (by default) text is copied to the clipboard immediately upon being selected. You can click and drag to perform a normal selection. Double-clicking selects a whole word. Triple-clicking selects an entire line. Quadruple-clicking performs a "smart select", matching recognized strings such as URLs and email addresses. You can add custom pointer actions in Settings > Pointer. I recommend using three-finger tap for smart selection, but you must ensure that *System Settings > Trackpad* does not have any other action already assigned to three-finger tap. If you hold shift while clicking the existing selection is extended. In fact, you can single click in one location and shift click in an other location to make a selection: no dragging needed. If you hold cmd while dragging it will create a noncontiguous selection. If you hold cmd and click on a URL it will be opened. If you hold cmd and click on a filename, it will be opened. There is special support for MacVim, TextMate, and BBEdit when you cmd-click on a text file's name: if it is followed by a colon and line number, the file will be opened at that line number. The current directory is tracked if you have your shell prompt set the window title, [as described here](http://www.faqs.org/docs/Linux-mini/Xterm-Title.html#toc4), or if you have [Shell Integration](documentation-shell-integration.html) installed. If you hold cmd and option while selecting, a rectangular selection will be made. If mouse reporting is enabled (in Settings > Profile > Terminal) and the currently running terminal application is using it, pressing option will temporarily disable it so you can make a selection. Right clicking on certain values shows helpful information in the context menu: - Right-clicking on a number shows its conversion to or from hex, or if it looks like a unix timestamp its representation in local time will be shown. - Right-clicking on a non-ASCII character shows its code point and UTF-8 representation. You can configure your pointing device's scroll gesture to send arrow keys in interactive programs by turning on Settings > Advanced > Scroll wheel sends arrow keys when in alternate screen mode, but it will only work if **Settings > Profiles > Terminal > Disable save/restore alternate screen** is turned off. A three-finger swipe left or right on a trackpad (if configured to "navigate") will select an adjacent tab. Middle clicking on a tab (if your pointing device has a middle button) closes it. #### Keyboard Every aspect of the keyboard can be configured in iTerm2. These keystrokes may be useful to remember: - Cmd+left arrow, Cmd+right arrow navigates among tabs. So does Cmd-{ and Cmd-}. - Cmd+number navigates directly to a tab. - Cmd+Option+Number navigates directly to a window. - Cmd+Option+Arrow keys navigate among split panes. - Cmd+] and Cmd+[ navigates among split panes in order of use. You can configure any key combination to perform any action in two places: in Settings > Keys, you can define global key shortcuts that affect all profiles. In Settings > Profiles > Keys, you can define key shortcuts that affect only a single profile. You can remap modifiers like Option and Cmd within iTerm2. Some users find that pressing Option frequently is uncomfortable, and configure iTerm2 to swap the function of the Option and Cmd keys. This is done in Settings > Keys under Remap Modifier Keys. If there is some key combination that you don't want to be affected by this change (such as Cmd-tab) add a new global shortcut key with the action Do Not Remap. iTerm2 allows you to define a global hotkey. This is a single keystroke that iTerm2 listens for even when another application has keyboard focus. When it is pressed, iTerm2 comes to the front. Press it again, and iTerm2 goes away. You can choose to bind the hotkey to a single dedicated window. For more on the hotkey window and other uses of hotkeys, see [Hotkeys](documentation-hotkey.html). #### Context menus By right-clicking in a session a context menu opens. You can use it to open a new session, perform various actions on selected text, or access frequently used features to affect the clicked-on session. #### Profiles Many settings are stored in profiles. A profile is a named collection of settings, and you can have as many of them as you like. Most users only have one profile, but if you find that you often connect to different servers, they may be useful for you. A key feature of a profile is that you can associate a command with it that is run when it begins. For instance, if you often ssh to a particular host, you could create a profile with the command "ssh example.com" to automate that process. --- # Source: https://iterm2.com/documentation-highlights.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Highlights for New Users This chapter describes features of iTerm2 that go beyond basic usage and are not generally found in other terminal emulators. #### Text Selection There are several ways to select text to copy to the clipboard: - You can [use the mouse](documentation-general-usage.html). - You can use the find feature's "mouseless copy" feature. To select text without using the mouse, press cmd-f to open the find field. Enter the beginning of the text you wish to copy and the find feature will select it in your window. Then press tab and the end of the selection will advance by a word. To move the beginning of the selection to the left, press shift-tab. At most one line of text can be selected this way. - You can use [Copy Mode](documentation-copymode.html). - You can bind keystrokes to create and adjust selections. In Prefs > Profiles > Keys you can assign keys to move the beginning or end of the selection by a single character, word, or line. No such keys are bound by default. #### Split Panes iTerm2 allows you to divide a tab into many rectangular "panes", each of which is a different terminal session. The shortcuts cmd-d and cmd-shift-d divide an existing session vertically or horizontally, respectively. You can navigate among split panes with cmd-opt-arrow or cmd-[ and cmd-]. You can "maximize" the current pane--hiding all others in that tab--with cmd-shift-enter. Pressing the shortcut again restores the hidden panes. #### Hotkey Window iTerm2 offers a special terminal window that is always available with a single keystroke. This window is called the "hotkey window" and is most commonly used for occasional administrative tasks. It is described in [Hotkeys](documentation-hotkey.html). #### Swap Cmd and Option iTerm2 allows you to remap modifiers. You have separate control over left and right command and option keys. One common need is to exchange cmd and option. To do this, go to Settings > Keys. Set Left option key to Left command key and Left command key to Left option key (and do the same for Right command and Right option if you please). You can add exceptions if you don't want certain combinations to be remapped (for example, cmd-tab) by adding a new global shortcut with the action "Do Not Remap" and the keystroke of the (unremapped) key you wish to keep unaffected by modifier remapping. #### Save Mark/Jump to Mark You can mark a location in a session with cmd-shift-M and then jump back to it with cmd-shift-J. This is useful, for instance, if you suspend your editor to compile a program and it emits errors. You can save a mark at that point and then return to your editor to fix the errors. As you work, you can jump back to the compilation errors with cmd-shift-J. #### Regular Expression Search When you open the find field (cmd-f) there is a down-arrow on the left of the field by the magnifying glass. Clicking it opens a menu of options in which you can enable regular expression search. The [ICU syntax](https://unicode-org.github.io/icu/userguide/strings/regexp.html#regular-expression-metacharacters) is used. #### Autocomplete Any text that exists in a tab or its scrollback buffer can be autocompleted in that tab. To use autocomplete, type the beginning of a word and then press cmd-;. An autocomplete window opens showing the top 20 choices for words beginning what you have entered. The list can be filtered by typing a subsequence. The filter can be reset by pressing backspace. If you make a selection and press return, it will be entered for you. If you make a selection and press tab, your autocomplete will be extended with the selection. #### Paste History Whenever text is copied or pasted in iTerm2 it is added to the paste history. You can access paste history with cmd-shift-H. It can be filtered by typing a subsequence, and the filter can be cleared by pressing backspace. You can choose to have your paste history saved to disk by turning that option on under Settings > General > Save copy/paste history to disk. #### Instant Replay Sometimes interactive programs will overwrite something of interest on the screen (for example, top(1) does this all the time). Normally, this would be lost forever. With Instant Replay, you can step back in time to see exactly what was on your screen at some point in the recent past. To enable, press cmd-opt-B. Once you are in instant replay mode, you can use the left and right arrow keys to navigate back and forward through time. Esc exits instant replay mode. By default, each session uses up to 4MB to save its instant replay history, and this can be adjusted under Settings > General > Instant Replay uses __ MB per session. Another benefit of Instant Replay is that it shows you the exact time that something appeared on your screen down to the second. This is useful when trying to figure out when an error occurred, for example. #### Full Screen You can press cmd-enter and iTerm2 will take up the entire screen. If you had a transparent background configured, it will be turned off upon entering full screen mode to reduce distractions. You can re-enable it with cmd-U. Unlike most macOS apps, iTerm2 can open a fullscreen window in the same desktop with no annoying animation if you disable Settings > General > Native full screen windows. #### High-Color Modes iTerm2 supports 256 color mode. To enable this for csh shells, set your terminal to xterm-256color (under Settings > Profiles > Terminal > Report Terminal Type). Some applications may need to be configured to support this mode. In vim, add this to your .vimrc: ``` set t_Co=256 ``` iTerm2 also supports 24-bit color. #### Focus Follows Mouse This option is off by default, but can be enabled under Settings > Pointer > Focus follows mouse. It only affects iTerm2 windows. #### Middle Button Paste If you have a three-button mouse, by default the middle button performs "paste". You can configure the behavior of the middle button, as well as many other kinds of clicks and gestures, in Prefs > Pointer. #### Cursor Finery When using a block cursor, it's hard to pick a cursor color that's visible against every background color. If you enable Smart cursor color (under Settings > Profiles > Colors) then the cursor color will be dynamically chosen to be visible against the text it is over and the adjacent cells. If you prefer a white or black cursor, you can use the "cursor boost" feature (under Settings > Profiles > Colors) to make all colors other than the cursor dimmer. Do you have trouble finding your cursor? You can turn on the cursor guide by toggling the View > Show Cursor Guide menu item or turning on Settings > Profiles > Colors > Cursor Guide. This can also be toggled by an escape sequence. For example, add this to your .vimrc: ``` let &t_ti.="\]1337;HighlightCursorLine=true\x7" let &t_te.="\]1337;HighlightCursorLine=false\x7" ``` If you've lost your cursor, press Cmd-/ or select View > Find Cursor and the cursor's position on the screen will be indicated very clearly #### Minimum Contrast Sometimes an application will display text with a color combination that is hard to read. Colorblind users in particular may find certain combinations hard to see if the colors differ only in hue and not brightness. If you enable minimum contrast (under Settings > Profiles > Colors > Minimum contrast, then iTerm2 will guarantee a minimum level of brightness difference between the foreground and background color of every character. If you set this to its maximum value, then all text will be black or white. #### Notification Center Support If you enable notifications (Settings > Profiles > Terminal > Send Notification Center alerts) then you'll receive messages when a terminal beeps, has output after a period of silence, or terminates. There's also [a proprietary escape sequence](documentation-escape-codes.html) to send a notification. You can adjust the kinds of notifications that get posted in Settings > Profiles > Terminal > Filter Alerts. #### Window Arrangements You can take a snapshot of your open windows, tabs, and panes with the menu option Window > Save Window Arrangement. You can restore this configuration with Window > Restore Window Arrangement, or you can choose to have it automatically restored when you start iTerm2 with Settings > General > Open saved window arrangement. #### Smart Selection Performing a quad-click does a "smart selection," which selects text under the pointer in a way appropriate to its content. For example, URLs, quoted strings, and email addresses (among many other objects) are recognized and selected in their entirety. You can also bind actions to a smart selection rule. The first action takes effect when you cmd-click on text matching the rule. All actions are added to the context menu when you right click on text matching the rule. #### Triggers Triggers are user-configurable regular expressions with associated actions that run when text is received that matches the regex. Actions include highlighting the matching text, showing an alert, sending text back, and more. One advanced use of a trigger is to capture output matching a regex and display just those matching lines in the toolbelt. For example, you could create a trigger that matches compiler errors. When you run Make the errors will appear on the side of your window and you can click each to jump right to it. More information is available at the [Captured Output](documentation-captured-output.html) manual. #### Tmux Integration iTerm2 is tightly integrated with tmux. The integration allows you to see tmux windows as native iTerm2 windows or tabs. The tmux prefix key is not needed, as native menu commands operate on tmux windows. For more information, please see the [iTerm2-tmux Integration](documentation-tmux-integration.html) document. #### Coprocesses Coprocesses are programs that run alongside iTerm2 and are bound to a single session. All output bound for the session is also routed as input to the coprocess. The coprocess's output acts like the user typing at the keyboard. Coprocesses can be used to automate tasks. For more information, see the [Coprocess](documentation-coprocesses.html) document. #### Dynamic Profiles If you have hundreds or thousands of profiles, look in to [Dynamic Profiles](documentation-dynamic-profiles.html). This feature allows you to define profiles in JSON. #### Automatic Profile Switching You can automatically change the current session's profile using [Automatic Profile Switching](documentation-automatic-profile-switching.html). For example, this would allow you to change the background color when you are on a production system. #### Inline Images iTerm2 can display images inline, including animated GIFs. The easiest way to use this feature is to install [Shell Integration and Utilities](documentation-utilities.html), which adds an `imgcat` script. #### Undo Close If you accidentally close a session, you get five seconds (by default; configurable in Settings > Profiles > Session) to undo it by pressing Cmd-Z. #### Shell Integration Shell Integration is a feature exclusive to iTerm2 that uses knowledge about your shell prompt to help you navigate from one shell prompt to another, record your command history, suggest most used directories, helps you re-run commands, download files from remote hosts with a click, upload files to remote hosts with drag and drop, and more. See the [Shell Integration](documentation-shell-integration.html) documentation for all the details. #### Password Manager iTerm2 can save your passwords in the Keychain. Use the Window > Password Manager menu item to open the password manager and enter your passwords. #### Timestamps Toggle View > Show Timestamps to indicate the time each line was last modified. This is useful for telling how long operations took or when a message was printed. #### Tab Bar on Left You can position the tab bar on the left side of the window. This is useful if you have a really large number of tabs. #### Open Quickly If you have lots of sessions you can quickly find the one you're looking for with Open Quickly. Select the View > Open Quickly menu item (cmd-shift-O) and then enter a search query. You can search by tab title, command name, host name, user name, profile name, directory name, badge label, and more. Open Quickly also lets you create new tabs, change the current session's profile, and open arrangements. If you start your query with a / then that gives you a shortcut to various commands. Enter a query of / to see them. #### Shell Integration and Utilities Shell integration consists of a shell script that's loaded when you create a new session or ssh to a remote host. It modifies your prompt so iTerm2 knows where it is. This enables a number of features, such as Copy Output of Last Command, Automatic Profile Switching when changing hosts, and more as described in [Shell Integration](documentation-shell-integration.html). When you install Shell Integration you'll be prompted to also install its Utilities. The Utilities are a collection of shell scripts that use iTerm2's unique features and make them easy to use. For example, you can upload or download files from a remote host, copy to the pasteboard from the command line (even over ssh!), and make fireworks explode from the cursor. It's described in [Utilities](documentation-utilities.html). --- # Source: https://iterm2.com/documentation-hotkey.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Hotkeys A hotkey is a keypress that iTerm2 responds to even if another application is active. iTerm2 recognizes three kinds of hotkeys: Toggle All Windows, Session Hotkeys, and Profile Hotkeys. ### Toggle All Windows This hotkey shows or hides all iTerm2 windows. It does not change their positions. It is meant for quickly switching between iTerm2 and other applications. Configure this in **Settings > Keys > Show/hide all windows with a system-wide hotkey**. Turn on the checkbox and then click in the text field beneath it and type the hotkey you'd like to use. ### Session Hotkeys You can assign a hotkey to a particular session. Select **Session > Edit Session** to modify properties of the current session. The preference window will open, and at the bottom of the *General* tab is a field where you can set a hotkey that opens iTerm2 to reveal that session. ### Dedicated Hotkey Windows A dedicated hotkey window is a window that is associated with a profile and has a hotkey attached to it. By pressing the hotkey, the window opens or closes. This is similar to the old Visor app. In its simplest form, it's a system-wide terminal window that you can open with a hotkey. iTerm2 allows you to assign multiple hotkeys to a single profile or even a single hotkey to multiple profiles. You can also assign the double-tap of a modifier. To create your first dedicated hotkey window, go to **Settings > Keys** and click **Create a Dedicated Hotkey Window**. This will create a new profile called **Hotkey Window**. You'll be prompted to configure the window. The following settings are available: - Pin hotkey window: If selected, the hotkey window remains open when another window gets keyboard focus. When off, the window will automatically hide when you select another window (whether in iTerm2 or another app) - Automatically reopen on app activation: If selected, this dedicated hotkey window will reveal itself when iTerm2 is activated (such as by clicking the dock icon or another iTerm2 window). - Animate showing and hiding: Controls whether hotkey windows animate in and out or quickly jump-cut in and out. - Floating window: When selected, the dedicated hotkey window can appear over other apps' full screen windows (provided the profile's **Window > Space** setting is **All Spaces**). Floating windows overlap the dock. - On Dock icon click: This setting configures what happens when the dock icon is clicked. If you want to assign multiple hotkeys to a single dedicated hotkey window, add them by clicking **Additional Hotkeys**. You can configure an existing hotkey window by clicking **Configure Hotkey Window** in **Prefs > Profiles > Keys**. --- # Source: https://iterm2.com/documentation-images.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Inline Images Protocol iTerm2 is able to display images within the terminal. Using a similar mechanism, it can also facilitate file transfers over any transport (such as ssh or telnet), even in a non-8-bit-clean environment. Just want to try it out and don't care about the protocol? Use the imgcat tool. [Download imgcat here](https://iterm2.com/utilities/imgcat) ### Example: imgcat Using the [imgcat](https://iterm2.com/utilities/imgcat) script, one or more images may be displayed in a terminal session. For example: Critically, animated GIFs are supported as of version 2.9.20150512. ### Retina Starting in iTerm2 version 3.2.0, Retina displays are properly supported. Previously, they would be double-size (one display "point" per image pixel rather than one display pixel per image pixel). If you prefer the old behavior, change **Prefs > Advanced > Show inline images at Retina resolution**. ### Protocol iTerm2 extends the xterm protocol with a set of proprietary escape sequences. In general, the pattern is: ``` ESC ] 1337 ; key = value ^G ``` Whitespace is shown here for ease of reading: in practice, no spaces should be used. ^G is the BEL character. You can use ST in place of ^G anywhere it is mentioned in this document. ST is the standard terminator for OSC sequences, and is formed by `ESC \`. For file transfer and inline images, there are two control sequences. The original one, which works on all remotely modern versions of iTerm2 is: ``` ESC ] 1337 ; File = [optional arguments] : base-64 encoded file contents ^G ``` The optional arguments are formatted as `key=value` with a semicolon between each key-value pair. They are described below. A new way of sending files was introduced in iTerm2 version 3.5 which works in tmux integration mode by splitting the giant control sequence into a number of smaller ones: First, send: ``` ESC ] 1337 ; MultipartFile = [optional arguments] ^G ``` Then, send one or more of: ``` ESC ] 1337 ; FilePart = base64 encoded file contents ^G ``` What size chunks should you use? Older versions of tmux have a limit of 256 bytes for the entire sequence. In newer versions of tmux, the limit is 1,048,576 bytes. iTerm2 also imposes a limit of 1,048,576 bytes. Finally, send: ``` ESC ] 1337 ; FileEnd ^G ``` KeyDescription of value name base-64 encoded filename. Defaults to "Unnamed file". size File size in bytes. Optional; this is only used by the progress indicator. width Width to render. See notes below. height Height to render. See notes below. preserveAspectRatio If set to 0, then the image's inherent aspect ratio will not be respected; otherwise, it will fill the specified width and height as much as possible without stretching. Defaults to 1. inline If set to 1, the file will be displayed inline. Otherwise, it will be downloaded with no visual representation in the terminal session. Defaults to 0. The width and height are given as a number followed by a unit, or the word "auto". - *N*: *N* character cells. - *N*px: *N* pixels. - *N*%: *N* percent of the session's width or height. - auto: The image's inherent size will be used to determine an appropriate dimension. ### More on File Transfers By omitting the `inline` argument (or setting its value to 0), files will be downloaded and saved in the *Downloads* folder instead of being displayed inline. Any kind of file may be downloaded, but only images will display inline. Any image format that macOS supports will display inline, including PDF, PICT, or any number of bitmap data formats (PNG, GIF, etc.). A new menu item titled *Downloads* will be added to the menu bar after a download begins, where progress can be monitored and the file can be located, opened, or removed. ### Detection Use the [Feature Reporting](https://iterm2.com/feature-reporting) protocol to detect the availability of inline images. ### Sample Code Sample code for displaying images may be found here. #### [imgls](https://iterm2.com/utilities/imgls) Provides an augmented directory listing that includes a thumbnail of each image in a directory. #### [imgcat](https://iterm2.com/utilities/imgcat) Displays one or more images inline at their full size. #### [it2dl](https://iterm2.com/utilities/it2dl) Downloads a file, but does not display it inline. #### [divider](https://raw.githubusercontent.com/gnachman/iTerm2/master/tests/divider) Draws a full-width, one line-tall graphical divider. --- # Source: https://iterm2.com/documentation-menu-items.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Menu Items [▸ iTerm2 Menu](javascript:showId('menu-iterm2')) [▾ iTerm2 Menu](javascript:hideId('menu-iterm2')) #### iTerm2 > Show Tip of the Day When you start using iTerm2 it will offer to show you a daily tip describing a feature. You can show a tip immediately by selecting this item. #### iTerm2 > Check for Updates Checks to see if a new version of iTerm2 is available. If Settings > General > Prompt for test-release updates is turned on then this includes beta versions; otherwise only stable versions are downloaded. #### iTerm2 > Toggle Debug Logging This saves helpful debugging information in memory. When it is toggled off it is saved to /tmp/debuglog.txt. #### iTerm2 > Copy Performance Stats This copies information about drawing speed to the pasteboard. This is useful when reporting issues relating to poor performance. #### iTerm2 > Capture GPU Frame This saves information about how the current session is drawn. This is useful when reporting issues relating to drawing errors in the GPU renderer. #### iTerm2 > Secure Keyboard Entry When this is enabled, the operating system will prevent other programs running on your computer from being able to see what you are typing. If you're concerned that untrusted programs might try to steal your passwords, you can turn this on, but it may disable global hotkeys in other programs. #### iTerm2 > Make iTerm2 Default Term Makes iTerm2 the default terminal for opening .command, .tool, .zsh, .csh, and .pl files. #### iTerm2 > Make Terminal Default Term You must hold down Option for this entry to be visible. Makes Terminal.app the default terminal for opening .command, .tool, .zsh, .csh, and .pl files. #### iTerm2 > Install Shell Integration This opens a window that guides you through the installation of the [Shell Integration](https://iterm2.com/shell_integration.html) features. [▸ Shell Menu](javascript:showId('menu-shell')) [▾ Shell Menu](javascript:hideId('menu-shell')) #### Shell > New Window/Tab This creates a new window or tab with the default profile. If the current session is a tmux integration session, then you will be prompted for whether to create a local or tmux session. #### Shell > New Window/Tab with Current Profile This creates a new tab using the same profile as the current session rather than the default profile. #### Shell > Duplicate Tab/Window Creates another tab with the same arrangement of split panes, profile, etc. #### Shell > Split Vertically/Horizontally These menu items allow you to divide a tab into two or more split panes. The panes can be adjusted by dragging the line that divides them. They will use the default profile. #### Shell > Split Vertically/Horizontally with Current Profile These menu items allow you to divide a tab into two or more split panes. The panes can be adjusted by dragging the line that divides them. They will use the profile of the current session. #### Shell > Save Contents Save the entire contents of the current session to a file. #### Shell > Save Selected Text Saves the selected text to a file. #### Shell > Close Terminates the current session. #### Shell > Close Terminal Window Terminates all sessions in the current window. #### Shell > Close All Panes in Tab Terminates all sessions in the current tab. #### Shell > Undo Close Undoes closing a session, tab, or window if the time limit has not expired yet. You can set the limit under **Settings > Profiles > Session > Undo can revive a session that has been closed for up to X seconds**. #### Shell > Broadcast Input > ... These options allow you to send keyboard input to more than one session. Be careful. - **Send input to current session only**: The default setting. - **Broadcast to all panes in all tabs**: Anything you type on the keyboard goes to all sessions in this window. - **Broadcast to all panes in current tab**: Anything you type on the keyboard goes to all sessions in this tab. - **Toggle broadcast input to current session**: Toggles whether this session receives broadcasted keystrokes within this window. - **Show Background Pattern Indicator**: If selected, sessions receiving broadcast input get an obnoxious red-stripe background. #### Shell > tmux > ... These commands let you interact with the tmux integration - **Detach**: Detaches from the tmux session associated with the current pane. It remains running in the tmux server. - **New tmux Window/Tab**: Creates a new tmux window, which appears in either a native window or tab, as requested. 8 **Dashboard**: The tmux dashboard is a view that lets you see all your tmux sessions and windows at a glance, adjust which are visible, rename them, and change the current tmux session. #### Shell > ssh > Disconnect Closes an SSH integration SSH connection. #### Shell > ssh > Download files Available when SSH Integration is in use. Opens a file picker showing files on currently connected remote hosts. Selecting one or more files downloads them. #### Shell > Print [I'm thinking printers!](https://theonion.com/new-apple-ceo-tim-cook-im-thinking-printers-1819572893/) [▸ Edit Menu](javascript:showId('menu-edit')) [▾ Edit Menu](javascript:hideId('menu-edit')) #### Edit > Undo Close Session/Tab/Window After you close a session, tab, or window then you have five seconds to undo it. The amount of time is configurable in Settings > Profiles > Session. #### Edit > Copy (With Styles) Hold down Option to turn Copy into Copy With Styles, which includes fonts and color information in the copied text. #### Edit > Copy with Control Sequences Copies the selected text, including control sequences that will reproduce the appearance (bold, colors, etc.) of the copied text when pasted into a terminal. Note that these will not be exactly the control sequences that were originally received, but instead a reconstruction that has the same effect. #### Edit > Copy Mode Enters *Copy Mode* which lets you make selections using the keyboard. See [Copy Mode](documentation-copymode.html) for details. #### Edit > Paste Special > Advanced Paste This opens the Advanced Paste window which lets you select a string from the pasteboard in recent history, select different representations of the current pasteboard, and modify the string before pasting it. You can modify it by appling a regex substitution, using various built-in modifiers (such as base-64 encoding), or edit it by hand. #### Edit > Paste Special > Paste Selection Pastes the currently selected text (which may differ from the text in the pasteboard). #### Edit > Paste Special > Paste File Base64-Encoded If there is a file on the pasteboard then this is enabled. When invoked, it base64-encodes the file and pastes the encoded value. #### Edit > Paste Special > Paste Slowly "Paste Slowly" pastes the current string in the clipboard, but it doesn't send the whole string at once. It is sent in batches of 16 bytes with a 125ms delay between batches. #### Edit > Paste Special > Paste Faster/Slower Adjusts the speed of pasting to be faster or slower. #### Edit > Paste Special > Paste Slowly Faster/Slower Adjusts the speed of slow pasting to be faster or slower. You must hold down option for this menu item to be visible. #### Edit > Paste Special > Warn Before Multi-Line Paste When enabled, you'll be warned before pasting more than one line. #### Edit > Paste Special > Limit Multi-Line Paste To Shell Prompt If *Warn Before Multi-Line Paste* is on, then this restricts it to warn only when you're at the shell prompt. It only works if shell integration is installed, since otherwise iTerm2 cannot tell when you're at the shell prompt. #### Edit > Paste Special > Prompt to Convert Tabs to Spaces when Pasting If *Prompt to Convert Tabs to Spaces when Pasting* is enabled, you'll be asked whether to convert tabs to spaces when pasting text containing tab characters. #### Edit > Paste Special > Warn Before Pasting One Line Ending in a Newline at Shell Prompt This requires shell integration to be installed to work. If you try to paste one line that ends in a newline while at the shell prompt and this is enabled, you'll get a confirmation dialog before the text is pasted. #### Edit > Replace Selection > Render Selection Natively Replaces the selection with a native rendering. For example, Markdown is replaced with formatted text with different font sizes, weights, etc. #### Edit > Replace Selection > Replace with Pretty-Printed JSON Replaces the selection with nicely formatted JSON. You can click in the margin to collapse sections. #### Edit > Replace Selection > Replace with Base 64-Encoded/Decoded Value Replaces the selection by encoding or decoding its value. Note the selection must be an entire line, not a portion of a line. #### Edit > Engage Artificial Intelligence Passes the value at the cursor to AI as a prompt. If there is no value, you'll be asked to provide a prompt. If you have shell integration installed and keyboard focus is on the terminal, then iTerm2 will use what you've typed so far at the command prompt as the input to the AI. #### Edit > Explain Output with AI This is available when there is a selection or a selected command. That text will be sent to AI to explain. The terminal contents will be modified, adding annotations detailing what parts of the text mean. The chat window will open so you can drill down more. #### Edit > Snippets Gives access to Snippets, which are saved bits of text that can be pasted quickly. You can change snippets in **Prefs>Shortcuts>Snippets**. #### Edit > Actions Gives access to Actions, which are user-defined actions similar to those that can be bound to a keystroke. You can change actions in **Prefs>Shortcuts>Actions**. #### Edit > Open Selection Opens the selected text using semantic history or as a URL, if it is URL-like. #### Edit > Jump to Selection Scrolls the selection to be visible. #### Edit > Selection Respects Soft Boundaries When enabled, vertical lines of pipe characters `|` will be interpreted as pane dividers (as in vim or emacs) and selection will wrap at them. #### Edit > Select Output of Last Command Requires shell integration to be installed. Selects the output of the last command. #### Edit > Select Current Command Requires shell integration to be installed. Selects the text of the current command entered at the command prompt. #### Edit > Find > Find Opens or focuses the find panel. Select the down arrow to the left of the search field to open the options menu, which lets you select case insensitivity and regular expression options. The default case sensitivity option of "Smart Case Sensitivity" performs a case-sensitive search if the search query contains any upper case letters. Otherwise, a case-insensitive search is performed. #### Edit > Find > Find Next/Previous Next and previous are, by default, reversed from the macOS standard because in a terminal you generally want to search backwards. You can use **Settings > Advanced > Swap Find Next and Find Previous** to get the standard behavior. #### Edit > Find > Find Globally Opens a window that lets you search all tabs at once. #### Edit > Find > Select Matches Converts Find matches into selections. #### Edit > Find > Find URLs Searches the current session for URLish looking strings. #### Edit > Find > Find All Smart Selection Matches Searches for all smart selection regular expressions at once. #### Edit > Find > Pick Result to Open Shows a shortcut next to each find match. Typing the shortcut opens it using smart selection or, if it is URL-like, using the default URL handler. #### Edit > Find > Filter Opens a panel where you can enter text to filter by. Non-matching lines are temporarily hidden until the filter panel is closed. #### Edit > Marks and Annotations > Set Mark Records the current scroll position. Use Edit > Jump to Mark to restore the scroll position. #### Edit > Marks and Annotations > Jump to Mark Makes the last mark (either created by **Set Mark** or by shell integration) visible by scrolling to it. #### Edit > Marks and Annotations > Next/Previous Mark Reveals the next/previous mark by scrolling and highlighting it in blue or red (red if it was tagged as a failing command). #### Edit > Marks and Annotations > Add Annotation at Cursor Adds an annotation to the word beginning at the cursor. An annotation is a scratchpad for you to write notes about a chunk of text in your history. #### Edit > Marks and Annotations > Next/Previous Annotations Reveals the next/previous annotation. Adds an annotation to the word beginning at the cursor. An annotation is a scratchpad for you to write notes about a chunk of text in your history. #### Edit > Marks and Annotations > Alerts > Alert on Next Mark When a mark is set (typically by [Shell Integration](documentation-shell-integration.html) when the currently running shell command terminates) then show an alert. #### Edit > Marks and Annotations > Alerts > Alert on Marks in Offscreen Sessions When disabled, **Alert on Next Mark** alerts even if the session is not currently visible. When enabled, only visible sessions (those that are in a non-hidden window in a selected tab) will alert. #### Edit > Clear Buffer Clears the entire terminal history and the mutable area. #### Edit > Clear Instant Replay Erases instant replay history for the current session. ### Edit > Clear Scrollback Buffer Clears scrollback history, preserving the mutable area. #### Edit > Clear to Start Of Selection Erases text between the start of the selection and the end. #### Edit > Clear to Last Mark Erases text between the last mark and the end. [▸ View Menu](javascript:showId('menu-view')) [▾ View Menu](javascript:hideId('menu-view')) #### View > Show Tabs in Fullscreen If enabled, tabs are shown in fullscreen windows. #### View > Toggle Full Screen Enters or exists full screen mode. iTerm2 supports both the standard macoS full screen mode, where the window occupies its own Space, and its traditional full screen mode that shares a Space with other windows. You can control which is used in **Settings > General > Native full screen windows**. #### View > Toolbelt > Set Default Width Saves the current window's toolbelt width as the default width for new windows' toolbelts. #### View > Toolbelt > Show Toolbelt This toggles the visibility of the Toolbelt on the right side of all windows. #### View > Toolbelt > Actions This toggles the visibility of the Actions tool, which shows actions you have configured under **Settings > Shortcuts > Actions**. #### View > Toolbelt > Captured Output This toggles the visibilty of the Captured Output tool. It shows captured output located with the Capture Output trigger. See [Captured Output](documentation-captured-output.html) for more information. #### View > Toolbelt > Codecierge This toggle the visibility of an AI assitant that helps you complete tasks in the terminal. #### View > Toolbelt > Command History This toggles the visibility of the Command History tool. It shows recently used commands. You must install [Shell Integration](documentation-shell-integration.html) for this to know your command history. #### View > Toolbelt > Jobs This toggles the visibility of the Jobs tool, which shows the running jobs in the current session, and allows you to send them signals. #### View > Toolbelt > Named Marks This toggles the visibility of the Named Marks tool, which helps you navigate to saved locations in the current session's history. In browser sessions, named marks take you to saved locations on a web page. #### View > Toolbelt > Notes This toggles the visibility of the Notes tool, which provides a freeform scratchpad in the toolbelt. Notes persist across restarts of the app and are saved in `~/Library/Application Support/iTerm2/notes.rtfd`. #### View > Toolbelt > Paste History This toggles the visibility of the Paste History tool, which shows recently pasted strings in the toolbelt. #### View > Toolbelt > Profiles This toggles the visibility of the Profiles tool, which lets you select profiles to open new windows, tabs, and split panes. #### View > Toolbelt > Recent Directories This toggles the visibility of the Recent Directories tool. It shows recently used directories sorted by a combination of recency and frequency of use. You must install [Shell Integration](documentation-shell-integration.html) for this to know your directory history. You can right click a directory to open a context menu that allows you to "start" a directory. This keeps it pinned at the bottom of the list so it's easy to find. #### View > Toolbelt > Snippets This toggles the visibility of the Snippets tool, which helps you send frequently used text strings. #### View > Use Transparency This toggles transparency. It only has an effect if you have configured your session to be transparent under Settings > Profiles > Window > Transparency. When Full Screen mode is entered, transparency is turned off by default, but you can select this menu item to re-enable it. #### View > Disable Transparency for Active Window When enabled, the active window will never be transparent. Inactive windows will respect the transparency setting from **Settings > Profiles > Window > Transparency**. #### View > Zoom In on Selection When a selection is present this is enabled. Zooming on a selection removes all other text from the session and lets you focus on just the zoomed-in-on text. Pressing escape will invoke Zoom Out when you are in the Zoom In state. #### View > Zoom Out Exits the *Zoom In on Selection* mode. #### View > Find Cursor Reveals the current cursor position. #### View > Show Cursor Guide Toggles the visiblity of the cursor guide which is a horizontal rule showing the location of the cursor. #### View > Show Timestamps Indicate the time of last modification of each line on the screen. #### View > Show Annotations Toggles the visibility of annotations. #### View > Show Composer Toggles the visibility of the Composer, a text area that you can edit using native macOS keystrokes. This is convenient for preparing complex inputs. #### View > Auto Command Completion Automatically shows a window with command completion suggestions as you type. Only usable when you have command history built up with [Shell Integration](documentation-shell-integration.html). #### View > Auto Composer Replaces the shell prompt with a macOS native text editing control. It offers filename and command completion, including over ssh when using SSH Integration. It requires [Shell Integration](documentation-shell-integration.html) to be installed in order to work. #### View > Open Quickly If you have lots of sessions you can quickly find the one you're looking for with Open Quickly. Select the View > Open Quickly menu item (cmd-shift-O) and then enter a search query. You can search by tab title, command name, host name, user name, profile name, directory name, badge label, and more. Queries are scored according to relevance and sorted by score. Open Quickly also lets you create new tabs, change the current session's profile, and open arrangements. If you start your query with a / then that gives you a shortcut to various commands. /a followed by an arrangement name restores the arrangement. /f restricts the query to existing sessions, excluding options to open new tabs, etc. /p restrics the query to profile names to switch the current session to. /t restricts the results to "open new tab" for matching profile names. #### View > Maximize Active Pane When there are split panes present, this toggles whether a given pane expands to fill the tab. When a maximized pane is present, the tab will be inscribed with a dotted outline. #### View > Size Changes Update Profile If enabled, modifying the text size using **View > Make Text Bigger** or **View > Make Text Smaller** will cause the session's profile to be updated with the new font size. #### View > Start Instant Replay Stepping through time allows you to see what was on the screen at a previous time. This is different than going back through the scrollback buffer, as interactive programs sometimes overwrite the screen contents without having them scroll back. Once in this mode, you can use the left and right arrow keys to step back and forward, respectively. The "esc" key exits this mode, as does clicking the close button in the bar that appears on the bottom. You can adjust the amount of memory dedicated to this feature in Settings > Instant Replay uses xx MB per session. The more memory you assign, the further back in time you can step. #### View > Tab Color Allows you to select a tint color for the tab, to make it easier to distinguish. You can also change the tab color in Settings > Profiles > Colors. [▸ Session Menu](javascript:showId('menu-session')) [▾ Session Menu](javascript:hideId('menu-session')) #### Session > Edit Session This opens a window that lets you change the settings of the current session without affecting any other sessions. Changes made in this panel will not be overridden by subsequent changes to the profile. Settings *not* cahnged in this panel will be affected by changes to the profile. #### Session > Run/Stop Coprocess Allows you to start and stop a coprocess linked to the current session. [Learn more about coprocesses](https://iterm2.com/documentation-coprocesses.html). #### Session > Restart Session After a session ends (e.g., because the shell exits) this menu item becomes enabled. It will re-run your profile's command in the same viewport as the terminated session. #### Session > Duplicate Session Creates a new session as similar as possible to the current session. The current directory is preserved and if you are using ssh integration it will connect to the same host. #### Session > Open Autocomplete... Shows the autocomplete window, which offers to finish typing a word that you've begun. [Learn more about autocomplete on highlights page](documentation-highlights.html). #### Session > Open Command History... If you use [Shell Integration](documentation-shell-integration.html) then Open Command History presents a list of recently used commands to select from. #### Session > Open Recent Directories... If you use [Shell Integration](documentation-shell-integration.html) then Open Recent Directories presents a list of recently used directories to select from. #### Session > Open Paste History... "Open Paste History" opens a window showing up to the last 20 values that were copied or pasted in iTerm2. You can search its contents by typing a (non-necessarily-consecutive) subsequence of characters that appear in the value. You can use arrow keys and enter to make a selection, or you can click on an item to choose it, and it will be pasted. If you enable the Save copy/pate history to disk preference then these values will persist across sessions of iTerm2. #### Session > Open AI Chat Creates a new AI chat and offers to link the current session to it. #### Session > Triggers The submenu contains the triggers defined for this session. You can enable or disable them by selecting a menu item. You can also add or edit triggers from here as well as control whether they are enabled for interactive applications. For more information see [Triggers](https://iterm2.com/documentation-triggers.html). #### Session > Reset Resets the internal state of the emulator and clears the screen. Use this if you get wedged in a bad state, like the wrong character set or mouse reporting mode is stuck. #### Session > Log > Log to File Logging saves all input received in a session to a file on disk. #### Session > Log > Import/Export Recording Lets you save or view an instant replay recording. #### Session > Bury Session/Buried Sessions Buries or unburies a session. See [Buried Sessions](documentation-buried-sessions.html) for details. [▸ Scripts Menu](javascript:showId('menu-scripts')) [▾ Scripts Menu](javascript:hideId('menu-scripts')) If you have scripts located in `$HOME/Library/Application Support/iTerm2/Scripts` they'll be added to this menu. For backward compatibility, `$HOME/Library/Application Support/iTerm/Scripts` will be used if `$HOME/Library/Application Support/iTerm2/Scripts` does not exist. #### Scripts > Manage > New Python Script Opens a UI to help you create a new Python API script. See the [Python API](https://iterm2.com/python-api) for more information. #### Scripts > Manage > Open Python REPL Opens a window with a Python REPL to facilitate working with the Python API. #### Scripts > Manage > Manage Dependencies Opens a window that lets you adjust dependencies of Python API scripts. This is meant for people authoring a script who need to bring in a new PyPI dependency. #### Scripts > Manage > Check for Updated Runtime Checks to see if a new version of the Python API Runtime is available. #### Scripts > Manage > Reveal Scripts in Finder Opens a Finder window in the Scripts folder. #### Scripts > Manage > Import Opens a file picker so you can pick a script file to import. It should have the extension `.its`. #### Scripts > Manage > Export Opens a file picker so you can pick a script file to export. This is used for sharing scripts with others. The export file will have the extension `.its`. #### Scripts > Manage > Console Opens the Script Console which shows which scripts are running, lets you view their logs, and has other developer tools for authors of Python API scripts. If you are using browser profiles then Javascript logs appear here as well. [▸ Profiles Menu](javascript:showId('menu-profiles')) [▾ Profiles Menu](javascript:hideId('menu-profiles')) This menu contains a list of profiles. Selecting one opens it in a new tab. Hold option while selecting a profile to open it in a new window, instead. #### Profiles > Open Profiles... This opens the "Profiles Window" which allows you to create new windows, tabs, or panes from one or more profiles. You can perform a search by entering text in the search field. Profile names and tags are searched, and the listed profiles are filtered as you type. You can use the up and down arrow keys to make a selection. Pressing enter will open a new tab, while shift-enter will open a new window. You can make multiple selections by holding down shift or cmd and clicking on profiles. The "New Tabs in New Window" button is enabled only when more than one profile is selected: it will open a new window and create a new tab for each profile selected. #### Profiles > Open All Opens all profiles in tabs (or in windows, if Option is pressed). [▸ Web Menu](javascript:showId('menu-web')) [▾ Web Menu](javascript:hideId('menu-web')) The Web menu is only visible when the current session is a web browser profile. #### Web > Open Location Puts the cursor in the URL bar. #### Back/Forward Standard web back/forward navigation. #### Web > Reload Page Reloads the current p age. #### Web > History Opens the history page, which shows the sites you have visited in chronological order. [▸ Window Menu](javascript:showId('menu-window')) [▾ Window Menu](javascript:hideId('menu-window')) #### Window > Arrangements > Save Window Arrangement Saves all of the window's positions, tabs, and split panes. You can opt to save them with contents to a file or to save them to the collection of window arrangements (without content) that can be restored later from **Window > Arrangements > Restore Window Arrangement (as Tabs) > (arrangement name)**. #### Window > Arrangements > Load Arrangement From File... Loads a saved arrangement file, which includes window contents. #### Window > Change Profile in Arrangement Use this to edit an existing arrangment. First, restore the arrangement. Then activate one of the sessions from the restored arrangement. Select **Change Profile in Arrangement** and you'll be asked to choose a profile. The arrangement will then be updated to use the selected profile for the corresponding session. #### Window > Edit Window Title Opens a dialog that lets you specify a window title as an interpolated string. #### Window > Tab > Edit Tab Title Opens a dialog that lets you specify a tab title as an interpolated string. #### Window > Split Pane > Lock Split Pane Width Toggles whether the active session's width is locked. A locked split pane does not change its width as the window is resized horizontally. #### Window > Password Manager Opens the password manager. #### Window > AI Chat Opens the AI Chat window. --- # Source: https://iterm2.com/documentation-preferences.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Preferences The preferences dialog contains the following sections: - [General](documentation-preferences-general.html) - [Appearance](documentation-preferences-appearance.html) - [Profiles](documentation-preferences-profiles.html) - [Keys](documentation-preferences-keys.html) - [Arrangements](documentation-preferences-arrangements.html) - [Pointer](documentation-preferences-pointer.html) - [Shortcuts](documentation-preferences-shortcuts.html) - [Advanced](documentation-preferences-advanced.html) --- # Source: https://iterm2.com/documentation-restoration.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Session Restoration Session restoration works by running your jobs within long-lived servers rather than as child processes of iTerm2. If iTerm2 crashes or upgrades, the servers keep going. When iTerm2 restarts, it searches for running servers and connects to them. The OS's window restoration feature preserves the content of your window, including scrollback history. iTerm2 marries the restored session to the appropriate server so you can pick up where you were. tl;dr watch this: [Demo Video](https://iterm2.com/misc/restoration-demo.mov) ### Notes - You must turn off **System Prefs > Desktop & Dock > Close windows when quitting an application**. For more information on system window restoration, please see [Apple's docs](https://support.apple.com/en-us/HT204005). - You must set **Prefs > General > Startup** to **Use system window restoration settings**. - Force quitting iTerm2, causing it to crash, or upgrading it when prompted should restore your sessions. *NOTE: Quitting iTerm2 with Cmd-Q will terminate your jobs and they won't be restored.* There is an advanced preference to change this behavior, though. - You can toggle this feature with **Prefs>Advanced>Enable session restoration.**, but you *must restart iTerm2 after changing this setting*. - A session that has had only its window contents restored and not the running processes will get a reverse video *Session Restored* banner. A properly restored session will pick up right where you left it. - If you reboot, your jobs will terminate and not be restored. The window contents should be restored. If you prefer for sessions not to be terminated when you quit iTerm2, turn off **Prefs>Advanced>User-initiated quit (cmd-q) of iTerm2 will kill all running jobs.** --- # Source: https://iterm2.com/documentation-scripting-fundamentals.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Scripting Fundamentals ## Introduction Sessions, tabs, windows, and the iTerm2 application itself each have bits of information that are useful to users and script writers. For example: a session has a working directory, a tab or a window may have a custom title, and the iTerm2 process has a theme such as light or dark mode. iTerm2 manages the storage and communication of this information with a system called "variables". A variable exists in some context. Each session, tab, and window has its own context. The application itself also has a context, called the global context. A variable has a name, such as `hostname`, and a value. The value is any data type encodable in JSON: numbers, booleans, strings, dictionaries, arrays, and null. There is also a special kind of variable that references a different context, allowing you to reach (for example) variables in the tab's context from its sessions' contexts. iTerm2 defines a number of built-in variables. There are also special contexts for user-defined variables. A user-defined variable has a value set by a control sequence or a script. Variables were originally invented for [Badges](https://www.iterm2.com/documentation-badges.html) as a way for users to embed text in a badge. For example, a shell script could set a user-defined variable containing the name of the current git branch, and that could be displayed in the badge. As the [Python scripting API](https://www.iterm2.com/python-api) was developed, it became clear that variables were a useful tool for sharing information between iTerm2 and scripts. See the [Variables Reference](documentation-variables.html) for information about built-in variables. Continue reading to see how variables can be used. ## Function Calls Scripts may register functions which users can invoke through various hooks. For example, you can bind the invocation of function call to a keypress or a [trigger](documentation-triggers.html). An *invocation* names the function, its arguments, and the values being passed to the function. For example, let us consider a hypothetical function that creates a new window using a passed-in initial working directory and profile. We'll name our function `create_window`, since every function has a name. A function may take parameters, and every parameter has a name. Let's call the parameter names for our example `initialDirectory` and `profileName`. To open a window with the initial working directory of `/etc` and profile `Default` we would use the following invocation syntax: ``` create_window(initialDirectory: "/etc", profileName: "Default") ``` Because every parameter is named the order of parameters does not matter. You could exchange them and it would work the same. If you wanted to use the working directory of the user's current session and you knew the function would be invoked in the session context (which is the context in which almost all function invocations occur) you could write: ``` create_window(initialDirectory: path, profileName: "Default") ``` The identifier `path` refers to a variable in the session context which holds the user's current working directory. A function may also return a value. That will be discussed in the section on interpolated strings below. To learn how to write your own functions, follow the [Python Scripting Tutorial](https://iterm2.com/python-api/tutorial/index.html). ### Built-in Functions iTerm2 provides a few built-in functions. There are not many because this is a relatively new feature and is still under development. - `iterm2.alert(title: str, subtitle: str, buttons: [str, ...])` - Shows a modal alert. If the buttons array is empty, OK will be shown. - `iterm2.count(array: [Any])` - Returns number of items in the array. - `iterm2.get_string(title: str, subtitle: str, placeholder: str, defaultValue: str, window_id: str?)` - Prompts the user for textual input. - `iterm2.move_tab_to_window(tab_id: str)` - Moves the tab into its own window. ## Expressions The preceding discussion of function calls showed how you can pass strings or paths to variables as arguments. The following types of expressions are supported: - Interpolated strings - Integers - Floating point - Array literals - Array dereferences - Function calls - Paths to variables ### Interpolated Strings These are described below. ### Integers These are decimal integer literals. For example, `-3`, `0`, and `2`. ### Floating point Floating point values look like `-1.2`, `0`, `2.3`, or `1.2e5`. ### Array Literals Array literals are of the form: ``` [ expression, expression, ... ] ``` They may contain zero or more expressions. ### Array dereferences Array dereferences are of the form: ``` path[index] ``` Where `path` is the path to a variable and `index` is a number. Yes, this is a very restrictive syntax! It is there for a very specific purpose (the `matches` array passed to Triggers' interpolated strings) and will be expanded in the future, if needed. ### Function calls A function call, as described above (e.g., `foo(bar: baz)`) is an expression. This implies that function calls may be composed. ### Paths to variables Variables in the current context can be referred to by a path like `jobName`, but you can also specify multi-part paths that refer to variables in different contexts. See the section **Following Context References**, below. ## Interpolated Strings Another way that varibles are exposed in iTerm2's user interface is through *interpolated strings*. An interpolated string is a string of text that contains embedded function calls or references to variables. iTerm2 borrows some of the Swift language's syntax for interpolated strings. This is not an attempt to implement the full Swift language, nor will iTerm2 ever contain a full-fledged language of its own. To embed an expression in a string, place it in `\(…)`. For example, you could set a session's name to: ``` The current host name is \(hostname) ``` The expression `hostname` will be replaced with its value. Since `hostname` is a variable defined in the session context, and iTerm2 defines it to be the name of the current hostname, the session's name will appear as something like `The current host name is example.com`. Here's an example showing the interpolated string in the Settings window and the resulting session title: * As a function call is a valid expression, these may also go in interpolated strings. The function's return value will be converted to a string and expanded just as an expression referencing a variable is replaced with the variable's value. For example, suppose you have a function `add(x,y)` that adds two numbers. Let's set the session name to: ``` Two plus three is \(add(x: 2, y: 3)) ``` The session's name as it appears in the tab bar would be `Two plus three is 5`. Interpolated strings may be nested. For example, imagine a function `cat(x,y)` that concatenates the value of `x` with the value of `y`. This would be a legal interpolated string: ``` \(cat(x: "Lorem \(cat(x: "ipsum ", y: "dolor")) sit ", y: "amet")) ``` Its value would be `Lorem ipsum dolor sit amet`. ### Escaping Interpolated strings use the following escaping rules: - `\n` -> Newline - `\a` -> Bel - `\t` -> Tab - `\r` -> Carriage return - `\\` -> Backspace - `\e` -> Esc - `\uxxxx` -> where x is a hex digit, gives the unicode codepoint ### Contexts When writing an interpolated string, you must be mindful of the context in which it is evaluated. For example, window titles are evaluated in the window's context. If you want to put the current session's hostname in the window title, you'd use `\(currentTab.currentSession.hostname)`. Likewise, tab titles are evaluated in the tab's context. ## Following Context References Some variables reference another context. For example, the session context has a variable named `tab` that references the session's containing tab's context. Likewise, the tab context has a `currentSession` variable that references the current session's context. You can chain variable references with `.`. For example, the working directory of the current session of the containing tab is given by: ``` tab.currentSession.path ``` ## Setting User-Defined Variables You can set user-defined variables that are attached to a session. These always begin with `user.`. For example, `user.gitBranch`. ### Shell Integration The easiest way to set a user-defined variable is with shell integration. Modify your shell's rc script by defining a function named iterm2_print_user_vars that calls iterm2_set_user_var one or more times. Here's an example that sets a user-defined variable called "gitBranch" to the git branch of the current directory. Pick your shell to see the version you need: bash | fish | tcsh | zsh ``` # bash: Place this in .bashrc. function iterm2_print_user_vars() { iterm2_set_user_var gitBranch $((git branch 2> /dev/null) | grep \* | cut -c3-) } ``` ``` # fish: Place this in ~/.config/fish/config.fish after the line # "source ~/.iterm2_shell_integration.fish". function iterm2_print_user_vars set -l git_branch (git branch ^/dev/null | sed -n '/\* /s///p') iterm2_set_user_var gitBranch "$git_branch" end ``` ``` # tcsh: Place this in .tcshrc alias get_current_branch "bash -c '((git branch 2> /dev/null) | grep \* | cut -c3-)'" alias _iterm2_user_defined_vars \ 'iterm2_set_user_var gitBranch `get_current_branch | base64`' # Note: you always need to manually base64 encode the second argument to # iterm2_set_user_var. If you want to define more than one variable, # use the pattern: # alias _iterm2_user_defined_vars \ # '(iterm2_set_user_var key1 value1; iterm2_set_user_var key2 value2; ...)' ``` ``` # zsh: Place this in .zshrc after "source /Users/georgen/.iterm2_shell_integration.zsh". iterm2_print_user_vars() { iterm2_set_user_var gitBranch $((git branch 2> /dev/null) | grep \* | cut -c3-) } ``` You could then set your badge to `\(user.gitBranch)`, for exmaple. ### Control Sequence User-defined variables may be set with the following escape sequence: ``` OSC 1337 ; SetUserVar=name*=*Base64-encoded value* ST ``` Here's a shell command that demonstrates setting `user.foo` to the value `bar`: ``` printf "\033]1337;SetUserVar=%s=%s\007" foo `echo -n bar | base64` ``` This is what iterm2_set_user_var sends. Generally you should use the *iterm2_print_user_vars* mechanism described above instead of sending this escape sequence directly. ### Python Script Use [`Session.async_set_variable()`](https://iterm2.com/python-api/session.html#iterm2.Session.async_set_variable) in a Python script to set a user-defined variable. --- # Source: https://iterm2.com/documentation-scripting.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Applescript iTerm2 features Applescript support which allows you to automate many aspects of its behavior. Quite a bit of customization is also possible by writing shell scripts. ### Applescript iTerm2 has sophisticated Applescript support allowing one to write stand-alone scripts to launch the application and open multiple sessions with profiles into either new tabs or new windows. You can also set some other parameters for a session such as foreground and background colors, and transparency. These scripts can then be saved as stand-alone executable applications. #### Autolaunching Scripts iTerm2 also supports autolaunching of an Applescript on startup. On startup, iTerm2 looks for an Applescript file in "~/Library/Application Support/iTerm2/Scripts/AutoLaunch.scpt". If it is found, the "AutoLaunch.scpt" script is launched and executed. If that folder does not exist, the legacy path of "~/Library/Application Support/iTerm/Scripts/AutoLaunch.scpt" will be used. #### User-Defined Scripts iTerm2 also supports launching of user defined scripts from the "Scripts" menu. The scripts need to be stored under the ~/Library/Application Support/iTerm/Scripts directory. You can create this directory if it does not already exist. iTerm2 checks this directory on startup. Scripts must be named with the extension .scpt or .app. # Reference ## Objects The basic objects are: window, tab, and session. The application has zero or more windows, each window has one or more tabs, and each tab has one or more sessions. Multiple sessions in a tab happen when there are split panes. ### Application The application exposes various properties and provides functions that are described in this section. For example: ``` tell application "iTerm2" create window with default profile end tell ``` 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 create window with default profile command "*command*" These commands create a window with the default profile. If you specify a command, it overrides the profile's command (which by default is to invoke `login`). Examples: set newWindow to (create window with default profile) set newWindow to (create window with default profile command "ls -l -R /") create window with profile "*name*" create window with profile "*name*" command "*command*" These commands create a window with a named profile. If you specify a command, it overrides the profile's command (which by default is to invoke `login`). Returns a reference to the new window. Examples: set newWindow to (create window with profile "Name Of Some Profile") set newWindow to (create window with profile "Name Of Some Profile" command "ls -l -R /") current window A reference to the window that most recently had keyboard focus. tell current window ... end tell windows A `windows` property exposes an array of terminal windows. Other windows, like the Settings panel, are not included. The following are standard Applescript idioms for accessing elements of an array of objects: ``` tell first window ... end tell repeat with aWindow in windows ... end repeat ``` ### Windows These functions and properties are provided by windows. For example: ``` tell application "iTerm2" tell current window create tab with default profile end tell end tell ``` There are many standard Applescript functions (e.g., to get the window's size and position) that are not documented here. create tab with default profile create tab with default profile command "*command*" create tab with profile "*name*" create tab with profile "*name*" command "*command*" Creates a tab with the default profile or a profile by name. If the command is specified, it is run instead of the profile's command/login shell. Returns a reference to the new tab. current session The `current session` is the session that would receive keyboard input if the window had keyboard focus. current tab The `current tab` is the tab that is selected in the window. hide hotkey window If this is a hotkey window, it hides it with the standard hotkey window animation and makes the previously active application active, if appropriate. hotkey window profile Returns the name of the hotkey window profile associated with this window, if any. id The window ID. Useful for commands like `screencapture`. is hotkey window Returns a boolean value which is true if the window is a hotkey window associated with a profile. name The window's name, as appears in the title bar. reveal hotkey window If this is a hotkey window, it reveals it with the standard hotkey window animation and makes it key and the application active. select Gives the window keyboard focus and brings it to the front. tabs An array of tabs. See the methods on Tab, below. toggle hotkey window Either shows or hides the hotkey window, if this is a hotkey window, using the standard animation. May make the app active or inactive. ### Sessions These functions and properties are provided by sessions. For example: ``` tell application "iTerm2" tell current session of current window split horizontally with default profile end tell end tell ``` background image This is a string property that gives a path to the background image of the session. close Terminates the session and closes its pane. Color properties Various properties which are readable and settable affect the session's colors: - background color - bold color - cursor color - cursor text color - foreground color - selected text color - selection color - ANSI black color - ANSI red color - ANSI green color - ANSI yellow color - ANSI blue color - ANSI magenta color - ANSI cyan color - ANSI white color - ANSI bright black color - ANSI bright red color - ANSI bright green color - ANSI bright yellow color - ANSI bright blue color - ANSI bright magenta color - ANSI bright cyan color - ANSI bright white color An example: ``` set foreground color to {65535, 0, 0, 0} ``` Because Applescript is kind of a dumpster fire, the standard syntax for a color is `{red, green, blue, alpha}` where each value is a number between 0 and 65535. answerback string The string sent when the `ENQ` escape sequence is received. columns The width of the session in character cells. contents Returns the visible contents of the session as a string. Each row is terminated with a newline. id Returns the session's unique identifier. is at shell prompt Indicates if the session is at a shell prompt accepting a command. Only works if [Shell Integration](https://iterm2.com/shell_integration.html) is installed; if not it will return false. is processing Returns a boolean indicating if the session received output recently. name A string property with the session's name as seen in its title bar. profile name The name of the profile the session was created with. A string. Read-only. rows The height of the session in character cells. set columns to *number* set rows to *number* Changes the size of the session. split horizontally with default profile split vertically with default profile split horizontally with default profile command "*command*" split vertically with default profile command "*command*" Splits the session either horizontally or vertically. If the optional *command* is provided then it is run in place of the profile's command. A horizontal split has a horizontal divider, while a vertical split has a vertical divider. Returns a reference to a session. split horizontally with profile "*name*" split vertically with profile "*name*" split horizontally with profile "*name*" command "*command*" split vertically with profile "*name*" command "*command*" Like the "default profile" commands, but uses a named profile instead of the default profile. split horizontally with same profile split vertically with same profile split horizontally with same profile command "*command*" split vertically with same profile command "*command*" Like the "default profile" commands, but uses the current session's profile. select Makes the session active in its tab. Does not affect which tab is selected or which window has keyboard focus. text A synonym for `contents`. transparency A floating-point value from 0 to 1 giving how transparent the session is. tty The name of the session's tty (e.g., /dev/ttys01). Returns a string. unique id A string uniquely identifying the session. variable "*name*" set variable named "*name*" to "*value*" Gets and sets the value of a variable by name. Variables are described in [Badges](https://iterm2.com/badges.html). You may only set user-defined variables, whose names always begin with "user.". write text "*text*" write text "*text*" newline NO Writes text to the session, as though you had typed it. Optionally without a newline. write contents of file "*filename*" Writes the contents of a file to the session as though you had typed it. ### Tabs These functions and properties are provided by tabs. For example: ``` tell application "iTerm2" tell current tab of current window select end tell end tell ``` close Closes the tab. current session The session in this tab that most recently had keyboard focus. index The index of the tab in the window, starting from 0. select Selects the tab, making it the current tab for the window. sessions An array of sessions. sessions An array of sessions in this tab. The index from 0 of the tab in its window. ## Supporting both old and new versions of iTerm2 If your application needs to support both the old and new Applescript syntax, this is the recommended technique: ``` on theSplit(theString, theDelimiter) set oldDelimiters to AppleScript's text item delimiters set AppleScript's text item delimiters to theDelimiter set theArray to every text item of theString set AppleScript's text item delimiters to oldDelimiters return theArray end theSplit on IsModernVersion(version) set myArray to my theSplit(version, ".") set major to item 1 of myArray set minor to item 2 of myArray set veryMinor to item 3 of myArray if major 2 then return true end if if minor 9 then return true end if if veryMinor < 20140903 then return false end if return true end IsModernVersion on NewScript() -- Return the modern script as a string here; what follows is an example. return "create window with default profile" end NewScript on OldScript() -- Return the legacy script as a string here; what follows is an example. return " set myTerm to (make new terminal) tell myTerm launch session \"Default\" end tell" end OldScript tell application "iTerm" if my IsModernVersion(version) then set myScript to my NewScript() else set myScript to my OldScript() end if end tell set fullScript to "tell application \"iTerm\" " & myScript & " end tell" run script fullScript ``` --- # Source: https://iterm2.com/documentation-search-syntax.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Search Syntax When iTerm2 presents a list of profiles, it usually includes a search box. The search box uses a special syntax that lets you tailor your searches to quickly find what you're looking for. ### Searching Profiles Each word in the search query must match at least one word in either the title or the tags of a profile in order for that profile to be matched by the query. For a word to be a match, it must be a substring. Query   Profile Name Matches? Linux **Linux** Yes x Linu**x** Yes z Linux No George L **George**'s **L**inux Machine Yes ### Operators You may prefix a phrase in the search query with an *operator* to narrow your query. These operators are defined: - The *name:* operator only tries to match words in the profile's name. - The *tag:* operator only tries to match words in the profile's tags. - The *command:* operator only tries to match words in the profile's command. Note that the command is only searched for words that explicitly use the `command` operator. Available in iTerm2 version 3.5.5 and later. ### Quoting You can require that two or more words occur in order by putting quotes in your query. For example: Query Profile Name Matches? "Linux machine" George's **Linux machine** Yes "machine Linux" Linux machine No ### Anchoring Normally, words in a query must match a substring of a word in the title or tags of a profile. You can require that a word in your query matches a prefix of a word in the title or tags by inserting a caret (^) before the word. You can require that a word in your query matches the suffix of a word in the title or tags by appending a dollar sign ($) after the word. For example, the query *^a* matches only profiles with words starting with "a". The query *a$* matches words ending in "a". The query *^a$* matches only the word "a". Query   Profile Name Matches? ^root [[email protected]](https://iterm2.com/cdn-cgi/l/email-protection) Yes ^root Groot! No root$ Groot Yes ^root$ Groot No ^root$ root Yes ### Combining Features You may combine quoting, operators, and anchors. The operator always comes first, followed by a caret, followed by a quoted string, followed by a dollar sign. Consider the following examples: ``` name:^"George's Linux Machine"$ ``` Three consecutive whole words in the profile's name must equal "George's Linux Machine". ``` name:"George's Linux Machine"$ ``` Would match a profile named "XGeorge's Linux Machine", unlike the previous example. ``` name:^"George's Linux Machine" ``` Would match a profile named "George's Linux MachineX", unlike the first example. ``` name:"George's Linux Machine" ``` Would match a profile named "XGeorge's Linux MachineX", unlike the first example. ``` name:^George's name:George's$ name:^George's$ ``` A word having the prefix, suffix, or exactly matching "George's" must occur in the profile's name to match these queries, respectively. --- # Source: https://iterm2.com/documentation-shell-integration.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Shell Integration iTerm2 may be integrated with the unix shell so that it can keep track of your command history, current working directory, host name, and more--even over ssh. This enables several useful features. Shell integration is compatible with zsh, bash, fish (2.3 and later), and tcsh. ### How To Enable Shell Integration This section describes the four ways to enable shell integration: - [Load it automatically.](#load-automatically) - [Use the **Install Shell Integration** menu item.](#download-and-run) - [Install it by hand.](#install-by-hand) - [Configure triggers appropriately.](#triggers) #### Load Automatically In iTerm2 version 3.5 and later you can enable shell integration by enabling **Load shell integration automatically** in **Settings > Profiles > General** in the **Command** section. This is available if your `Command` is set to `SSH` or if it's set to `Login Shell` and your shell is supported. #### Install Shell Integration Menu Item To modify your shell's dotfiles to load shell integration, you can select the menu item **iTerm2 > Install Shell Integration**. You'll first be asked whether you wish to install the Utilities. Utilities consist of a number of shell scripts that provide useful functionality, such as displaying inline images, performing file transfer, or customizing the display. Next you can choose to download and run an installer or to do an internet-free install. The download-and-run option will type this command for you: ``` curl -L https://iterm2.com/shell_integration/install_shell_integration.sh | bash ``` Alternately, select **Internet-Free Install**. This runs a sequence of commands to determine your shell, install files, and modify your dotfiles to load shell integration automatically. #### Install By Hand If you prefer to have control over the process of modifying your environment, you can manually install shell integration by creating files and editing your shell's configuration. Select your shell to see the appropriate instructions: bash | fish | tcsh | zsh ``` curl -L https://iterm2.com/shell_integration/bash \ -o ~/.iterm2_shell_integration.bash ``` Next, you need to load the script at login time. You need to add the following command to ~/.bash_profile or ~/.profile. If you already have .profile then add it there, otherwise add it to .bash_profile. Put it at the end because other scripts may overwrite the settings it needs, such as `PROMPT_COMMAND`. ``` source ~/.iterm2_shell_integration.bash ``` ``` curl -L https://iterm2.com/shell_integration/zsh \ -o ~/.iterm2_shell_integration.zsh ``` Next, you need to load the script at login time. Add this to the end of ~/.zshrc: ``` source ~/.iterm2_shell_integration.zsh ``` ``` curl -L https://iterm2.com/shell_integration/fish \ -o ~/.iterm2_shell_integration.fish ``` Next, you need to load the script at login time. Add this to the end of ~/.config/fish/config.fish: ``` source ~/.iterm2_shell_integration.fish ``` ``` curl -L https://iterm2.com/shell_integration/tcsh \ -o ~/.iterm2_shell_integration.tcsh ``` Next, you need to load the script at login time. Add this to the end of ~/.login: ``` source ~/.iterm2_shell_integration.tcsh ``` #### Triggers Installing a login script on every host you connect to is not always an option. To be sure, modifying root's login script is usually a bad idea. In these cases you can get the benefits of shell integration by defining triggers. The following triggers are of interest: - Report User & Host - Report Directory - Prompt Detected Use these triggers to tell iTerm2 your current username, hostname, directory, and the location of the shell prompt. Suppose you have a shell prompt that looks like this: ``` [[email protected]](https://iterm2.com/cdn-cgi/l/email-protection):/home/george% ``` It exposes the username, hostname, and working directory. We can harvest those with a regular expression. First, define a trigger with this regex: ``` ^(\w+)@([\w.]+):.+% ``` It captures the username and hostname from the example prompt above. Select the action "Report User & Host". Set the trigger's parameter to: ``` \1@\2 ``` Then create another trigger with the action **Report Directory**. This regular expression will extract the directory from the example prompt: ``` ^\w+@[\w.]+:([^%]+)% ``` Set this trigger's parameter to ``` \1 ``` Make sure both triggers have their **Instant** checkbox enabled so they'll take effect before a newline is received. Finally, add a regular expression that matches the start of your prompt and give the "Prompt Detected" action. This causes a "mark" to be added, which is a blue triangle visible to the left of this line (or a horizontal line above, if Auto Composer is enabled). You may specify a user name or host name alone to **Report Host & User**. If you give just a user name then the previous host name will be preserved; if you give just a host name then the previous user name will be preserved. To change the user name only, give a parameter like `user@`. To change the host name only, give a parameter like `example.com`. ### Features Shell Integration enables numerous features: #### Marks These are saved locations in history. They make it easy to navigate to previous shell prompts or other locations of interest. #### Select Output of Last Command The menu item under **Edit** selects the output of the last-run command. #### Alert when current command finishes running. iTerm2 will present a modal alert when a long-running command finishes, if you ask it to. #### View information about commands. You can see the return status code, working directory, running time, and more for shell commands entered at the prompt in the past. #### Download files from remote hosts with a click. You can right click on a filename (e.g., in the output of **ls**) to download it. #### Drag-drop files to upload with scp. Hold down option and drag-drop a file from Finder into iTerm2 to upload it. #### View command history. It can be seen and searched in the toolbelt or quickly accessed in a popup window. #### Easy access to recently and frequently used directories. iTerm2 remembers the directories you use, sorting them by "frecency" (frequency and recency of use) and giving you access to them in the toolbelt and in a popup window. #### Assign profiles to hostnames, usernames, or username+hostname combinations. Sessions will automatically switch profiles as you log in and out according to rules you define. #### Ensures the command prompt always starts at the left column, even when the last command didn't end in a newline. Each of these features are described in more detail below. #### Offscreen Command Line When part of a command's output is scrolled off the top of the screen, the originating prompt is shown there. #### Auto Composer Auto Composer replaces your shell's prompt with a macOS-native text view that uses native editing conventions. #### Command Selection Click on a command to select it; then **Find**, **Filter**, and **Select All** will be restricted to that command's output. ### How it works Shell Integration works by configuring your shell on each host you log into to send special escape codes that convey the following information: - Where the command prompt begins and ends. - Where a command entered at the command prompt ends and its output begins. - The return code of the last-run command. - Your username. - The current host name. - The current directory. ### How to use it #### Marks When shell integration is enabled, iTerm2 automatically adds a mark at each command prompt. Marks are indicated visually by a small blue triangle in the left margin. You can navigate marks with Cmd-Shift-Up and Down-arrow keys. If you have a multi-line prompt and would like to customize the mark's location, add this to your PS1 at the location where the mark should appear: For zsh: ``` %{$(iterm2_prompt_mark)%} ``` For bash: ``` \[$(iterm2_prompt_mark)\] ``` Fish users can place this line somewhere in their fish_prompt function: ``` iterm2_prompt_mark ``` This feature is not supported in tcsh. For zsh and bash users: if you are unable to modify PS1 directly (for example, if you use a zsh theme that wants to control PS1), you must take an extra step. Add `export ITERM2_SQUELCH_MARK=1` before the shell integration script is sourced. Add the `iterm2_prompt_mark` as directed above to your prompt through those means available to you. #### Alert on next mark iTerm2 can show an alert box when a mark appears. This is useful when you start a long-running command. Select **Edit>Marks and Annotations>Alert on next mark** (Cmd-Opt-A) after starting a command, and you can go do something else in another window or tab. When the command prompt returns, a modal alert will appear, calling attention to the finished job. #### Command status The mark on a command line will turn red if a command fails. You can right click the mark to view its return code. #### Download with scp You can right-click on a filename (e.g., in the output of **ls**) and select **Download with scp from hostname**, and iTerm2 will download the file for you. A new menu bar item will be added called **Downloads** that lets you view downloaded files and track their progress. #### Upload with scp If you drop a file (e.g., from Finder) into iTerm2 while holding the option key, iTerm2 will offer to upload the file via scp to the remote host into the directory you were in on the line you dropped the file on. A new menu bar item will be added called **Uploads** that lets you view uploaded files and track their progress. #### Command history With shell integration, iTerm2 can track your command history. The command history is stored separately for each username+hostname combination. There are four places where this is exposed in the UI: ##### Command history popup You can view and search the command history with **Session>Open Command History...** (Shift-Cmd-;). ##### Autocomplete Commands in command history are also added to Autocomplete (Cmd-;). If **Settings>General>Save copy/paste history and command history to disk** is enabled, then command history will be preserved across runs of iTerm2 (up to 200 commands per user/hostname). ##### Toolbelt A command history tool may be added to the toolbelt by selecting **Toolbelt>Command History**. Bold commands are from the current session. Clicking on one will scroll to reveal it. Double-clicking enters the command for you. Option-double-clicking will output a "cd" command to go to the directory you were in when it was last run. ##### Command Completion iTerm2 will present command completion suggestions automatically when **View>Auto Command Completion** is selected. #### Recent Directories With shell integration, iTerm2 will remember which directories you have used recently. The list of preferred directories is stored separately for each username+hostname combination. It is sorted by "frecency". There are two places it is exposed in the UI: ##### Recent Directories popup You can view and search your recently and frequently used directories in **Session>Open Recent Directories...** (Cmd-Opt-/). ##### Toolbelt A **Recent Directories** tool may be added to the toolbelt by selecting **Toolbelt>Recent Directories**. Double-clicking a directory will type its path for you into the current terminal. Option-double-click will enter a "cd" command for you. You can also right-click on a directory to toggle its "starred" status. A starred directory will always appear at the bottom of the list so it is easy to find. #### Automatic Profile Switching Please see the documentation at [Automatic Profile Switching](https://iterm2.com/automatic-profile-switching.html). #### Shell Integration for root If you'd like to be able to use shell integration as root, you have two options. The first option, presuming you use bash, is to become root with `sudo -s` (which loads your `.bashrc` as root) and add this to your `.bashrc`: ``` test $(whoami) == root && source "${HOME}/.iterm2_shell_integration.bash" ``` The alternative is to use Triggers to emulate shell integration as described above. ### Limitations By default, shell Integration does not work with tmux or screen. If you'd like to use it with tmux, add this to your login script prior to loading shell integration: ``` export ITERM_ENABLE_SHELL_INTEGRATION_WITH_TMUX=1 ``` It works well with tmux integration (`tmux -CC`) but not with the regular tmux UI. #### A Note on SCP iTerm2 can do uploads and downloads with scp as described above. There are a few things you should know. iTerm2 links in libssh2, and does not shell out to scp. It respects /etc/known_hosts and ~/.ssh/known_hosts, and will update the latter file appropriately. Host fingerprints are verified. Password, keyboard-interactive, and public-key authentication are supported. Private keys by default come from ~/.ssh/id_rsa, id_dsa, id_ed25519, or id_ecdsa, and may be encrypted with an optional passphrase. iTerm2 respects ssh_config files, but only a subset of the commands are understood: - Host - HostName - User - Port - IdentityFile Settings pulled from ssh_config override the hostname and user name provided by shell integration. The shell integration-provided host name is used as the text against which **Host** patterns are matched. The following files are parsed as ssh_config files, in order of priority: - ~/Library/Application Support/iTerm/ssh_config - ~/.ssh/config - /etc/ssh_config If you have trouble, see [SCP Not Connecting](https://gitlab.com/gnachman/iterm2/-/wikis/scp-not-connecting) on the wiki. If you use SSH Integration then file transfer happens over the SSH Integration framing protocol rather than by using scp. This is generally more reliable because it doesn't require opening a new connection. --- # Source: https://iterm2.com/documentation-smart-selection.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Smart Selection iTerm2 offers a Smart Selection feature that simplifies making selections on semantically recognizable objects. #### How do I use Smart Selection? A quad-click (four clicks of the left mouse button in quick succession) activates Smart Selection at the mouse cursor's position. By default, the following kinds of strings are recognized: - Words bounded by whitespace or line boundaries. - C++-style pairs of identifiers separated by double colons, such as "namespace::identifier". - Filesystem paths, such as "/foo/bar/baz.txt". - Quoted strings such as "foo bar". - Java or Python-style include paths, such as "foo.bar.baz". - URIs with the schemes: mailto, http, https, ssh, or telnet. - Objective-C selectors like "@selector(foo:bar:)". - Email addresses. #### How do I Change Smart Selection Rules? Under Settings>Profiles>Advanced, you may edit the smart selection rules. In addition to a regular expression, each rule also has a Precision attribute, which takes a value of Very Low, Low, Normal, High, or Very High. Intuitively, it refers to how sure one can be that when a rule's regular expression finds a match that it is what the user intended. For example, the "Word" rule is low precision (it matches almost every time), while the "HTTP URL" rule is very high precision (it almost never produces false positives). This allows the "HTTP URL" rule to take precedence when both match, unless the "Word" rule matches a much longer string. That might happen, for instance, if there were a non-URL character after a URL followed by a lot more text. The precision levels have a very strong effect, so it's very rare for a lower precision rule to take precedence over a higher precision rule. When editing rules, it is advised that you experiment with different precision levels and different kinds of strings to find one that works well. A collection of test cases may be found at smart_selection_cases.txt. When Smart Selection is activated, iTerm2 tries each regular expression. For a given regex, various strings on the screen are tested until the longest match is found. Only matches that include the character under the cursor are of interest. The longest such match is added to a pool of "selection candidates". Each candidate is assigned a score equal to its length in characters. Among the candidates in the highest precision class (where Very High is the highest class and Very Low is the lowest) with any matches, the higheset scoring one is used as the selection. #### Actions Actions may be associated with smart selection rules. When you right click in a terminal, smart selection is performed at the cursor's location. Any smart selection rule that matches that location will be searched for associated actions, and those actions will be added to the context menu. A cmd-click on text matching a smart selection rule will invoke the first rule. The following actions are defined: - Open File: Opens the file using the default system application. - Open URL: Opens the URL using the default system browser. - Run Command: Runs the command using `/bin/sh -c` in the background. Output goes to the Script Console. - Run Coprocess: Starts a [coprocess](documentation-coprocesses.html). - Send Text: Sends text as though it was typed by the user. - Run Command in Window: Opens a new window and runs the command in it. - Copy: Copies the string to the pasteboard. Each action has a parameter. The meaning of the parameter depends on the action. For example, for the **Open URL** action the parameter should be a URL. The value you put in the `Parameter` field may contain special substrings which get substituted with values determined at runtime. By default, a legacy syntax is used with the following substitutions: - `\0`: The full text of the match. - `\1`: The first match group (captured using parentheses in the regular expression). - `\2`...`\9`: Subsequent match groups. - `\d`: The current directory. - `\u`: The current user name. If you're sshed then you must install [Shell Integration](documentation-shell-integration.html) for this to be known. - `\h`: The current host name. If you're sshed then you must install [Shell Integration](documentation-shell-integration.html) for this to be known. - `\n`: Newline - `\\`: Backslash If you check the **Use interpolated strings for parameters** checkbox, then a more modern syntax is used. See the [interpolated string](documentation-scripting-fundamentals.html) documentation for details. For example, a parameter of `\(path)` is equivalent to the legacy syntax `\d`. In addition to the standard variables that are available in an interpolated string evaluated in a Session context, an array of strings called `matches` is defined. `matches[0]` is the full text of the match and `matches[i]` is the `i`th capture group for `i` > 0. When using interpolated strings, the [usual escaping rules](documentation-scripting-fundamentals.html#interpolated-strings) apply. #### Regular Expressions Regular expressions conform to the [ICU regular expressions](https://unicode-org.github.io/icu/userguide/strings/regexp.html) rules. --- # Source: https://iterm2.com/documentation-status-bar.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Status Bar iTerm2 offers a configurable, scriptable status bar. The purpose of the status bar is to show up-to-date information about the environment you're working in and to offer useful interactions where appropriate. ### Setup Go to **Settings > Profiles > Session**. Turn on **Status bar enabled**. Then click **Configure Status Bar** to begin setting up your status bar configuration. ### Components A status bar is composed of components. iTerm2 ships with a number of components: #### System Resource Monitors - **Battery Level** - Shows a graph of battery level over time as well as a charging indicator. - **CPU Utilization** - Shows a graph of CPU utilization over time. - **Memory Utilization** - Shows a graph of RAM utilization over time. - **Network Throughput** - Shows a graph of upload and download throughput over time. #### Shell Information - **Current Directory** - Shows the current working directory. Use Shell Integration to keep this accurate when sshing. - **Host Name** - Shows the current hostname. Use Shell Integration to keep this accurate when sshing. - **User Name** - Shows the current username. Use Shell Integration to keep this accurate when sshing. - **Job Name** - Shows the name of the current foreground job and its parent processes. - **git state** - Shows the current git branch, whether it's dirty, and the number of commits ahead or behind of `origin`. #### Miscellaneous - **Clock** - Shows the current time and date. - **Custom Action** - A button that performs a configurable action. #### UI Affordances - **Composer** - A field for editing commands before sending them to the shell. - **Search Tool** - A search field for performing searches over terminal history. - **Filter** - A field for filtering terminal contents. - **Action** - A button that activates a programmable action, much like a key-binding action. - **Snippet** - A button that pastes text from Snippets, as configured in *Prefs>Shortcuts>Snippets*. - **Triggers** - A button that activates a menu allowing you to enable or disable triggers. #### Spacers - **Empty Space** - An empty component. NOTE: This is only available when using the "stable positioning" layout algorithm. - **Fixed-size Spacer** - Adds a fixed amount of space between components - **Spring** - Adds a variable amount of space between components. NOTE: This is only available when using the "tight packing" layout algorithm. #### Python API Hooks - **Interpolated String** - Shows the value of an [interpolated string](documentation-scripting-fundamentals.html). - **Call Script Function** - Shows the result of a [Python API function call](documentation-scripting-fundamentals.html). You can also write your own components in Python. See the examples section of the Python API docs for a [working demo](https://iterm2.com/python-api/examples/statusbar.html). Custom components show up at the end of the list (you may need to scroll down to see them). ### Adding and Removing To add a component to the status bar, drag it from the top section to the *Active Components* section. To remove a status bar component, select and press backspace. You can also drag it out of the *Active Components* section. ### Configure Component Many components can be configured. To modify a component's settings, select it in the *Active Components* section. Then click **Configure Component**. Some settings are common to all or most components: - **Background Color** - If set, this overrides the default background color. - **Text Color** - If set, this overrides the default text color. - **Priority** - When there isn't enough space to show all the components, they will be removed from lowest to highest priority. All components default to priority 5. - **Compression Resistance** - When using the "tight packing" layout algorithm, the compression resistance acts like a spring constant. A higher value means the allocated space will shrink more slowly than for components with lower compression resistance. - **Size Multiple** - When using the "stable positioning" layout algorithm, the size multiple sets how wide this component is relative to the standard width. It can be a floating-point value. - **Minimum Width** - Gives the minimum width of the component in points. - **Maximum Width** - Gives the maximum width of the component in points. #### Clock Component The clock component has a **Date Format** setting. It defaults to `M-DD h:mm`. See [Unicode TR 35-1](http://www.unicode.org/reports/tr35/tr35-31/tr35-dates.html#Date_Format_Patterns) for the syntax. #### git status Component The git status component lets you configure the polling interval in seconds. It periodically runs git commands in the current directory to check its status, and this determines the time between updates. The git command is run in a sandbox that does not allow writing to the filesystem outside of `/tmp` and `/var` to avoid side-effects. #### Interpolated String The interpolated string component has a `String Value` parameter where you can enter the interpolated string you wish to display. It is evaluated in the context of the current session. #### Function Call The function call component has a `Label` that is displayed in the status bar and a `Function call` parameter that gives the Python API function call to invoke when the component is clicked. ### Interactions Some components allow user interaction. #### git status Click the `git status` component to get the following options: - **Commit** - Runs `git commit`. A window will open for you to enter the commit message if needed. - **Add & Commit** - Runs `git commit -a`. A window will open for you to enter the commit message if needed. - **Stash** - Runs `git stash` - **Log** - Runs `git log` and shows the result in a popover. - **Pull origin master** - Runs `git pull origin master` and opens a window if necessary. - **Push origin master** - Runs `git push origin master` and opens a window if necessary. - **Check out recent branches** - Runs `git checkout `. The most recently used branches are listed. #### Job Name Click the component to open a popover showing the job tree in this session. This feature is only available on macOS 10.14 and later. #### Working Directory Click the component to view the recent working directories on this host. Select one to issue a `cd` command to enter it. ### Advanced Settings The **Advanced** button lets you configure settings that affect the status bar as a whole. You can set the separator color, background color, and default text color. When unset, these take reasonable values. You can also change the font. Not all fonts will look good because of size and alignment issues. You can also adjust the layout algorithm. #### Tight Packing Algorithm The tight packing algorithm treats each component as a spring which is more or less compressible and has a minimum (and sometimes maximum) size. It begins by trying to show all components. If their minimum sizes cannot all be satisfied then they are removed from lowest to highest priority. In the case of a tie the leftmost component with the lowest priority is removed. Once the set of visible components has been thus determined, their widths are set in proportion to their spring constants. This algorithm gets the highest density of status bar components at the cost of their jumping around whenever a value changes. #### Stable Positioning Algorithm The stable positioning algorithm first determines which components will be visible by adding them from highest to lowest priority. Every component is allocated the base width times its size multiple (which defaults to 1). The base width is no less than the largest minimum width of all the visible components. Spacers adjacent to components that are not visible will also be removed to make the best use of space. This is the default algorithm. ### Auto-Rainbow Pressing this buton assigns text colors to the active components in a pleasing variety of rainbow colors. No unicorns were harmed in the making of this feature. --- # Source: https://iterm2.com/documentation-tmux-integration.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # tmux Integration iTerm2 is integrated with tmux, allowing you to enjoy a native user interface with all the benefits of tmux's persistence. ### Introduction Normally, when you use tmux, multiple virtual windows are displayed in a single "physical" window. You can manipulate the environment by issuing commands to tmux. This poses a few problems: - Some keystroke must be dedicated to tmux to enter its command mode (^B, by default, which means moving the cursor to the left in emacs or an interactive shell becomes more difficult). - You have to ssh to the remote host more than once to get more than one view of your tmux session's window. - You have to learn tmux commands. - To adjust split panes, you have to enable mouse reporting, even if you don't want it otherwise. - Some built-in features of your terminal emulator don't work as well as they would if you weren't using tmux: for instance, you can't access tmux's scrollback history as easily or quickly as you can in a normal terminal window. Also, tmux's find feature isn't as good as iTerm2's. For many users, a terminal multiplexer would be a great way to work, but they don't want to accept the drawbacks. iTerm2's tmux integration solves these problems. When you run "tmux -CC", a new tmux session is created. An iTerm2 window opens and it acts like a normal iTerm2 window. The difference is that when iTerm2 quits or the ssh session is lost, tmux keeps running. You can return to the host you were ssh'ed into and run "tmux -CC attach" and the iTerm2 windows will reopen in the same state they were in before. A few use cases come to mind: For users who do most of their work in ssh: - Restore the environment you had at work when you get home. - No more anxiety about letting System Update reboot! For everyone: - Collaborate with another user by having two people attach to the same tmux session. ### Usage You should be able to use tmux as always. Just add the -CC argument to its invocation. In practice, this means running one of these commands: - tmux -CC - tmux -CC attach When you run tmux -CC, what you'll see on that terminal is a menu: ``` ** tmux mode started ** Command Menu ---------------------------- esc Detach cleanly. X Force-quit tmux mode. L Toggle logging. C Run tmux command. ``` - If you press esc, the tmux windows will close and the tmux client will exit. - If you press esc and nothing happens, then the tmux client may have crashed or something else has gone wrong. Press "X" to force iTerm2 to exit tmux mode. You may need to run "stty sane" to restore your terminal's state if the tmux client did crash. - If you want to report a bug, press L and reproduce the issue. The tmux protocol commands will be written to the screen. - If you want to run a tmux command that isn't available through the menus, you can press C. A dialog box opens and you can enter a command. For example, "new-window". In general, you don't need to run commands to perform the most common actions. The following iTerm2 actions affect tmux: - Close a session, tab, or window: Kills the tmux session or window. - Split a pane: Splits the tmux window using the split-window command. - Resize a split pane: Resizes tmux split panes using the resize-pane command. - Resize a window: Tells tmux that the client size has changed, causing all windows to resize. Windows are never larger than the smallest attached client. A gray area on the right or bottom of a window indicates that a physical window is larger than the maximum allowed tmux window size. One consequence of this rule is that all tmux windows/tabs will contain the same number of rows and columns. - Create a window or tab using the Shell->tmux menu: Creates a new tmux window. - Detach using Shell->tmux->Detach: Detaches from the tmux session. All tmux windows are closed. You can get them back with tmux -CC attach. ### Limitations There are a few limitations of tmux integration which are related to the design of tmux. - A tab with a tmux window may not contain non-tmux split panes. - A tab with split panes may have "empty" areas. This is because tmux wants every tmux window to be the same size, but our split pane dividers are not exactly one cell by one cell in size. ### Configuration Check *Settings > General > tmux* for configuration settings. You can also adjust whether to open the tmux Dashboard when connecting to a session with a large number of windows. You can open the tmux Dashboard by selecting the menu item *Shell > tmux > Dashboard*. See also the tmux section of [General Settings](documentation-preferences-general.html). ### Best Practices For practical tips on how to configure iTerm2 for use with tmux integration in the real world, please see [tmux Integration Best Practices](https://gitlab.com/gnachman/iterm2/wikis/tmux-Integration-Best-Practices). --- # Source: https://iterm2.com/documentation-touch-bar.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Touch Bar As with many applications, you may customize the controls on the touch bar with **View > Customize Touch Bar**. The following controls are available: #### Man Page Opens the manpage for the command behind the cursor. #### Color Preset When selected, this opens a scrollable list of color presets. Choosing one changes the current terminal's colors to use the preset. #### Function Keys There are two function keys controls. The first, labeled *Function Keys Popover*, opens a scrollable list of function keys when pressed. It is compact but requires two taps to press a function key. The second, labeled *Function Keys*, shows a scrollable list of function keys at all times. It takes more space but is quicker to use. If you install [Shell Integration](https://www.iterm2.com/documentation-shell-integration.html) and [Utilities](https://www.iterm2.com/documentation-utilities.html), then you'll get a command *it2setkeylabel* that lets you configure what each function key's label says. You can configure each application you use (such as vim or emacs) to set the labels appropriately. #### Add Mark The *Add Mark* touch bar control saves the current location in history. You can navigate among marks with Cmd-Shift-Up and Cmd-Shift-Down. There are also touch bar controls to navigate marks. #### Next/Previous Mark Navigates to the next or previous mark. If you have [Shell Integration](https://www.iterm2.com/documentation-shell-integration.html) installed, each command prompt inserts a mark, so the previous mark is usually the previous shell prompt. #### Autocomplete Suggestions If you have [Shell Integration](https://www.iterm2.com/documentation-shell-integration.html) installed, iTerm2 can remember you command history. That history is used to make suggestions for commands, which appear in this touch bar control. #### Status The status touch bar control shows a user-configurable message. If you install [Shell Integration](https://www.iterm2.com/documentation-shell-integration.html) and [Utilities](https://www.iterm2.com/documentation-utilities.html), then you'll get a command *it2setkeylabel* that lets you configure what the status control says. For example, it could display the git branch of the current directory. Tapping it scrolls to the location where the status was last changed. For example, suppose you want to show your current git branch in the touch bar. - Select the menu item **View > Customize Touch Bar** - Drag "Your Message Here" button into the touch bar - Modify PS1 to include `\[$(it2setkeylabel set status "$message")\]`. For example: ``` PS1='\s-\v\$\[$(~/.iterm2/it2setkeylabel set status \ "$(test -d .git && (git rev-parse --abbrev-ref HEAD) || (echo -n "Not a repo"))")\] ' ``` #### Custom Buttons You can define custom touch bar buttons in **Prefs > Keys > Add Touch Bar Item**. You can then add the item to your touch bar from **View > Customize Touch Bar**. --- # Source: https://iterm2.com/documentation-triggers.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Triggers A trigger is an action that is performed when text matching some regular expression is received in a terminal session. #### How to Create a Trigger To create a trigger, open the **Settings** panel. Select the **Profiles** tab. Choose the profile to which you wish to add a trigger. Then select the **Advanced** tab. Click the **Edit** button in the **Triggers** section. A panel opens that displays any existing triggers. You can click the **+** button to add a new trigger. Triggers have a regular expression, an action, an optional parameter, and may be marked as *Instant*. #### Regular Expression Regular expressions conform to the [ICU regular expressions](https://unicode-org.github.io/icu/userguide/strings/regexp.html) rules. Text that is written to the screen including the BEL control code are sent to the regex matcher for evaluation. Only one line at a time is matched. By default, matching is performed when a newline or cursor-moving escape code is processed. If a line is very long, then only the *last* three wrapped lines are used (that is, the last three lines as seen on the display). This is done for performance reasons. You can change this limit in Advanced Settings > Number of screen lines to match against trigger regular expressions. #### Actions The following actions are available: - Annotate: Associates a note with a matching text. - Bounce Dock Icon: Makes the dock icon bounce until the iTerm2 window becomes key. - Capture Output: Save the line to the Captured Output toolbelt tool. See [Captured Output](documentation-captured-output.html). The parameter is text to send (as though it had been typed) when you double-click on an entry in the Captured Output tool. - Change Style: Modifies the style of matching text. Fold to Named Mark: Collapses all lines between the matching line and a preceding named mark with a given name. - Highlight Line: The entire line containing text matching the regex in the trigger will change color. The parameter sets the color. - Highlight Text: The text matching the regex in the trigger will change color. The parameter sets the color. - Inject Data: Inserts bytes into the input stream. These can be text or control sequences. - Invoke Script Function: Executes a function call defined using the Python API. - Make Hyperlink: The text matching the regex in the trigger will become a hyperlink which you can open with Cmd-Click. The parameter sets the URL. - Open Password Manager: Opens the password manager. You can specify which account to select by default. - Post Notification: Posts a notification with Notification Center. - Prompt Detected: Informs iTerm2 that the shell prompt begins at the start of the match. Used to emulate Shell Integration features. If the prompt is one line long then use Instant. - Report Directory: Tells iTerm2 what your current directory is. You can use this to enable [Shell Integration](documentation-shell-integration.html) features without installing the scripts. The parameter is your current directory. - Report User & Host: Tells iTerm2 what your user or host name is. You can use this to enable [Shell Integration](documentation-shell-integration.html) features without installing the scripts. To specify just a user name, say `user@`. For just a host, say `@host`. For both, say `user@host`. - Ring Bell: Plays the standard system bell sound once. - Run Command: Runs a user-defined command. - Run Coprocess: Runs a [Coprocess](documentation-coprocesses.html). - Run Silent Coprocess: Runs a [Coprocess](documentation-coprocesses.html) but do not show text that's being received (it only goes to the coprocess). - Send Text: Sends user-defined text back to the terminal as though the user had typed it. - Set Mark: Sets a mark. You can specify whether you'd like the display to stop scrolling after the trigger fires. - Set Named Mark: Associates a name with the matching range. Various features help you navigate to named marks such as the Toolbelt tool and Open Quickly. - Set Title: Sets the session's title. - Set User Variable: Assigns a value to a user-defined [variable](https://iterm2.com/documentation-variables.html). - Show Alert: Shows an alert box with user-defined text. - Stop Processing Triggers: When this action is invoked no triggers further down the list will be invoked for the current text. #### Parameter? Various actions (Run Command, Run Coprocess, Post Notification, Send Text, and Show Alert) require additional information. This is specified in the "Parameters" field. When the paramter is a text field with freeform entry, some special values are defined: Value Meaning \0 The entire value matched by the regular expression. \1, \2, ..., \9 The nth value captured by the regular expression. \a A BEL character (^G). \b A backspace character ^H. \e An ESC character (ascii 27). \n A newline character. \r A linefeed character. \t A tab character. \xNN A hex value NN (for example: \x1b sends ascii code 27, an ESC). #### Instant When *Instant* is set, the trigger will fire once per line as soon as the match occurs, without waiting for a newline. This was added for the benefit of the *Open Password Manager* trigger, since password prompts usually are not followed by a newline. This may cause certain regular expressions (for example, ".*") to match less than they otherwise might. #### Example The [iTerm2-zmodem](https://github.com/RobberPhex/iTerm2-zmodem) project demonstrates hooking up iTerm2 to zmodem upload and download. --- # Source: https://iterm2.com/documentation-utilities.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Utilities iTerm2 has a collection of shell scripts that help you take advantage of some of its unique features. When you install [Shell Integration](documentation-shell-integration.html) from the **iTerm2 > Install Shell Integration** menu, you're asked if you'd like to install the Utilities Package as well. This page describes these utilities. If you prefer to install only the utilities (without also installing Shell Integration) you can find them [here](https://github.com/gnachman/iTerm2-shell-integration/tree/main/utilities). Most of the utilities work without Shell Integration. ### Components The Utilities Package contains the following programs: #### imgcat The `imgcat` program displays images inline in your terminal. It supports all standard image formats, including animated GIFs. ``` Usage: imgcat filename [filename...] or cat image | imgcat ``` #### imgls Lists the files in a directory with thumbnail previews for images. ``` Usage: imgls [filename...] ``` #### it2attention Requests attention. Can bounce the dock icon or show a fireworks animation at the cursor position. ``` Usage: it2attention start Begin bouncing the dock icon if another app is active it2attention stop Stop bouncing the dock icon if another app is active it2attention fireworks Show an explosion animation at the cursor ``` #### it2check Checks if the terminal emulator is iTerm2. ``` Example: it2check && echo This is iTerm2 || echo This is not iTerm2 ``` #### it2copy Copies text to the pasteboard. Works over ssh. Accepts either standard input or a named file. ``` Examples: cat file.txt | it2copy it2copy file.txt ``` For this to work you must enable **Prefs > General > Applications in terminal may access clipboard**. #### it2dl The `it2dl` program downloads files. This is useful when you are ssh'ed to a remote host. The downloaded files are placed in your *Downloads* folder. #### it2getvar Fetches a session variable. For a list of session variables, see the [Badges](documentation-badges.html) page. ``` Example: it2getvar session.name ``` #### it2setcolor Configures iTerm2's colors. ``` Usage 1) To set a specific color to an RGB value: it2setcolor name color [name color...] For example: it2setcolor fg fff name is one of: fg bg bold link selbg selfg curbg curfg underline tab black red green yellow blue magenta cyan white br_black br_red br_green br_yellow br_blue br_magenta br_cyan br_white color is of the format: RGB (three hex digits, like fff) RRGGBB (six hex digits, like f0f0f0) cs:RGB (cs is a color space name) cs:RRGGBB (cs is a color space name) The color space names accepted in the color are: srgb (sRGB, the default if none is specified) rgb (Apple's old device-independent colorspace) p3 (Apple's fancy large-gamut colorspace) 2) To switch to a named color preset: it2setcolor preset name For example: it2setcolor preset 'Light Background' 3) To reset the current tab's color to the system default: it2setcolor tab default ``` #### it2setkeylabel Configures touch bar function key labels. ``` Usage: it2setkeylabel set Fn Label Where n is a value from 1 to 20 it2setkeylabel set status Label Sets the Touch Bar "status" button's label it2setkeylabel push [name] Saves the current labels with an optional name. Resets labels to their default value, unless name begins with a . character. it2setkeylabel pop [name] If name is given, all key labels up to and including the one with the matching name are popped. ``` Recommended usage for customizing an application is to set key labels and then push with a *name* of a concatenation of the app's name (e.g., "emacs") and a random number. When the app exists, pop to that same name. #### it2ul Uploads a file. Works over ssh. ``` Usage: it2ul [destination [tar flags]] If given, the destination specifies the directory to place downloaded files. Further options are passed through to tar. See your system's manpage for tar for details. ``` If used without arguments, the file goes to the current directory. When you run this, you'll be prompted to select one or more files. Next, iTerm2 creates a tar.gz file containing those files and base-64 encodes them. The it2ul script receives it, decodes it, and untars it with -xzfC. Any arguments you provide go after a lone - argument, #### it2universion Sets the unicode version for the current session. The key difference is that unicode 8 and unicode 9 use different width tables for emoji. Most apps aren't updated to use the unicode 9 tables, but Unicode 9 produces nicer results with fewer overlapping characters. ``` Usage: it2universion set 8 it2universion set 9 it2universion push [name] Saves the current version with an optional name. it2universion pop [name] If name is given, all versions up to and including the one with the matching name are popped. ``` ``` Usage: it2dl filename ``` ### Location The Utilities Package places shell scripts in `$HOME/.iterm2/` and creates aliases to them at the bottom of `$HOME/.iterm2_shell_integration.$SHELL`. --- # Source: https://iterm2.com/documentation-variables.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Variables Variables are used to communicate information between components such as Python scripts and shell scripts. They are described in depth in [Scripting Fundamentals](documentation-scripting-fundamentals.html). ## Reference Jump to context: [Session](#session-context) | [Tab](#tab-context) | [Window](#window-context) | [Global](#global-context) ### Session Context The following variables are defined in the context of a session: #### Session Name - `autoNameFormat` - This is an interpolated string from which the `autoName` variable is computed. It can be modified by changing the "Session Name" field in **Edit Session…**, by a trigger that sets the session name, or by an OSC control sequence that sets the icon title. It is initialized to the profile name when a new session is created. - `autoName` - The result of evaluating the `autoNameFormat` interpolated string. This attempts to match the user's intuition of the what the session's name is. - `name` - The formatted name as it appears in the tab bar (excluding tmux integration decoration). For example, if the profile is configured to show the session name and job, this would take a value like `My Profile (vim)`. - `presentationName` - The session name exactly as it appears in the session title bar. - `terminalIconName` - The "icon" title, as set by the control sequence OSC 0 or OSC 1. - `terminalWindowName` - The "window" title, as set by the control sequence OSC 0 or OSC 2. - `triggerName` - The last session name set by a trigger. #### Terminal - `columns` - Session's width in columns - `commandLine` - Command line of the current foreground job (job name including arguments) - `jobName` - The name of the current foreground job (e.g., "emacs") - `jobPid` - The process ID of the current foreground job in this session. - `mouseReportingMode` - A number indicating how mouse events are reported. -1: Not reported, 0: button clicks reported, 1: not currently implemented, 2: reports clicks and drags, 3: reports clicks, drags, and movement - `parentSession` - The session that was current when this sessionw as created. This is an alias to the context of that session so you can access its variables. - `pid` - The process ID of the root process in this session (typically `login`). - `processTitle` - The (perhaps modified by the process) title of a process from its argv. - `rows` - The session's height in rows - `selection` - The currently selected text. - `selectionLength` - The length in UTF-8 bytes of the currently selected text. - `termid` - Window, tab, and pane number as used in the `$TERM_SESSION_ID` environment variable. - `tty` - The path to the local TTY device - `uname` - Information about the operating system on the current host. - `shell` - The shell on the current host. - `sshIntegrationLevel` - 0: No ssh integration. 1: Basic ssh integration. 2: Full ssh integration with all features available. - `homeDirectory` - The home directory on the current host. - `applicationKeypad` - A boolean indicating if the session is in application keypad mode. - `mouseInfo` - An array with seven values: Mouse x, mouse y, currently pressed button, number of consecutive button clicks, array of modifiers pressed, a bitmask of the side-effects of clicking, mouse state. - `bellCount` - Number of times the bell has rung. #### Shell Integration These values require shell integration to be installed. - `hostname` - The current hostname - `lastCommand` - The last command run in the session - `path` - The current working directory (this works without shell integration, but not if you ssh elsewhere) - `username` - The current user name #### Logging - `autoLogId` - When automatic logging is enabled, this is the random number portion of the filename. - `creationTimeString` - A string giving the initial creation time of the session, used as part of the filename when automatic logging is enabled - `logFilename` - If set, the filename that logging goes to. If unset, logging is off. New in version 3.4.7. #### tmux Integration - `tmuxClientName` - The name of the tmux session when tmux integration is in use (e.g., `user@localhost`). - `tmuxPaneTitle` - The title of the tmux window pane. - `tmuxRole` - Unset if tmux integration is not in use. Otherwise, is "gateway" for the session in which `tmux -CC` is running or "client" in tmux integration sessions. - `tmuxStatusLeft` - In tmux integration, the value of the left side of the status bar. - `tmuxStatusRight` - In tmux integration, the value of the right side of the status bar. - `tmuxWindowPane` - In tmux integration, this gives the window pane number. - `tmuxWindowTitle` - If tmux integration is in use, this gives the name of the window title from tmux. - `tmuxWindowPaneIndex` - In tmux integration, this gives the index of the window pane. It corresponds to the `pane_index` property in tmux. #### References to Other Contexts - `iterm2` - A reference to the variables belonging to the application (i.e., the global context) - `tab` - A reference to the variables belonging to the tab containing this session. - `user` - A context for user-set variables. Variables may be set with a custom control sequence or by using the [Python scripting API](https://www.iterm2.com/python-api). They are often set when using shell integration. See [**User-Defined Variables**](#user-defined-variables) for more information. #### Other - `badge` - The value of the badge. Note that the user can enter an interpolated string in the UI, but this value contains the string result of evaluating it. - `id` - A unique identifier for the session - `profileName` - The name of the current profile. - `mouseInfo` - Describes the last mouse event. Is an array: `[x coord, y coord, button number, click count, array of modifiers, bitmask of side effects, event type]`. `x coord` is 0-based and gives the location in columns from the leftmost column. `y coord` is 0 at the first line in history, including lines which have since been lost if there are more lines of history than the maximum. `button number` is 0 for left, 1 for right, and 2 or greater for other buttons. `click count` is 1 for single click, 2 for double click, etc., and isn't artifically bounded. `array of modifiers` contains numbers for each modifier key that is pressed. They keys are: Control = 1; Option = 2; Command = 3; Shift = 4. `bitmask of side effects` comes by summing these values: Modify selection = 1; Perform action = 2; Open target (e.g., a URL or file) = 4; Report = 8; Move cursor = 16; Move find-on-page start location = 32; Open password manager = 64; Drag = 128. `event type` is 0 for mouse-up, 1 for mouse-down, 2 for drag. #### User-Defined Variables The only variables that users may directly control are those in the "user" scope of a session. For example, you could set a variable named "gitBranch" to the name of the current git branch. This value would then be available to display in the session title, badge, or other places, and would be available to Python API scripts. You'd reference it as `user.gitBranch`. See ["Setting User-Defined Variables" in *Scripting Fundamentals*](documentation-scripting-fundamentals.html#setting-user-defined-variables) for details on setting them. ### Tab Context - `id` - The unique identifier for this tab. - `titleOverrideFormat` - An interpolated string giving the title to use for the tab. If not set, the session's title will be used. Note the session's title is configurable in **Prefs > Profiles > General > Title** and is not necessarily equal to the `autoName`, but may be derived from it (or not). - `titleOverride` - The value of `titleOverrideFormat` after evaluating it as an interpolated string. - `tmuxWindow` - In tmux integration, this is the tmux window number this tab represents. - `tmuxWindowTitle` - In tmux integration, this is the tmux window title. It will only be set if the tmux option `set-title` is on. It comes from evaluating the tmux `set-titles-strings` option. - `tmuxWindowName` - In tmux integration, this is the tmux window name. - `title` - The fully formatted title as it appears in the tab bar. #### References to Other Contexts - `currentSession` - A reference to the context of the active session in this tab. - `iterm2` - A reference to the variables belonging to the application (i.e., the global context) - `window` - A reference to the context of the enclosing window ### Window Context #### References to Other Contexts - `currentTab` - A reference to the context of the active tab. - `iterm2` - A reference to the variables belonging to the application (i.e., the global context) #### Window Title - `titleOverride` - The value from evaluating the interpeted string in `titleOverrideFormat`, if set. - `titleOverrideFormat` - The window's interpolated string title. If not set, the current tab's title is used. - `currentTab` - The context of the current tab. #### Other - `id` - The window ID. - `frame` - An array of integers giving the x origin, y origin, width, and height. - `style` - The window style. Takes one of these values: `normal`, `non-native full screen`, `native full screen`, `full-width top`, `full-width bottom`, `full-height left`, `full-height right`, `bottom`, `top`, `left`, `right`, `no-title-bar`, `compact`, `accessory`. - `number` - The window number. Corresponds to the keyboard shortcut that switches to the window. Begins at 1. Unlike the keyboard shortcut, this is set even if the number is larger than 9. - `isHotkeyWindow` - A boolean indicating if this is a hotkey window. ### Global Context - `effectiveTheme` - A space-delimited list of words describing the OS theme (e.g., "dark", "light highContrast", "dark minimal") - `localhostName` - The best guess of what localhost's hostname is - `pid` - The process ID of the iTerm2 app --- # Source: https://iterm2.com/documentation-web.html [Table of Contents](#) Introduction - [Highlights for New Users](https://iterm2.com/documentation-highlights.html) - [General Usage](https://iterm2.com/documentation-general-usage.html) User Interface - [Menu Items](https://iterm2.com/documentation-menu-items.html) - [Settings](https://iterm2.com/documentation-preferences.html) - [Touch Bar](https://iterm2.com/documentation-touch-bar.html) - [Copy Mode](https://iterm2.com/documentation-copymode.html) - [Fonts](https://iterm2.com/documentation-fonts.html) - [Profile Search Syntax](https://iterm2.com/documentation-search-syntax.html) - [Command Selection and Command URLs](https://iterm2.com/documentation-command-selection.html) - [Status Bar](https://iterm2.com/documentation-status-bar.html) Features - [Automatic Profile Switching](https://iterm2.com/documentation-automatic-profile-switching.html) - [Badges](https://iterm2.com/documentation-badges.html) - [Buried Sessions](https://iterm2.com/documentation-buried-sessions.html) - [Captured Output](https://iterm2.com/documentation-captured-output.html) - [Coprocesses](https://iterm2.com/documentation-coprocesses.html) - [Hotkeys](https://iterm2.com/documentation-hotkey.html) - [Session Restoration](https://iterm2.com/documentation-restoration.html) - [Shell Integration](https://iterm2.com/documentation-shell-integration.html) - [Smart Selection](https://iterm2.com/documentation-smart-selection.html) - [tmux Integration](https://iterm2.com/documentation-tmux-integration.html) - [Triggers](https://iterm2.com/documentation-triggers.html) - [Utilities](https://iterm2.com/documentation-utilities.html) - [Web Browser](https://iterm2.com/documentation-web.html) - [AI Chat](https://iterm2.com/documentation-ai-chat.html) Scripting - [Scripting Fundamentals](https://iterm2.com/documentation-scripting-fundamentals.html) - [Scripting Variables](https://iterm2.com/documentation-variables.html) - [Python API](https://iterm2.com/python-api) - [Scripting with AppleScript (Deprecated)](https://iterm2.com/documentation-scripting.html) Advanced - [Dynamic Profiles](https://iterm2.com/documentation-dynamic-profiles.html) - [Inline Images Protocol](https://iterm2.com/documentation-images.html) - [Proprietary Escape Codes](https://iterm2.com/documentation-escape-codes.html) # Web Browser ## Overview iTerm2 includes built-in web browsing capabilities. Web browser sessions fit into iTerm2's existing window > tab > split pane hierarchy just like terminal sessions, allowing you to browse the web alongside your terminal work. ## Getting Started ### Enabling the Browser - Install the [browser plugin](https://iterm2.com/browser-plugin.html) to enable full functionality - Create a new profile - Go to **Settings > Profiles > General** - Set **Profile Type** to **Web Browser** **Note for Enterprise Users:** Administrators can block the browser plugin by restricting bundle ID `com.googlecode.iterm2.iTermBrowserPlugin`. ### Disabling Browser Features If you prefer not to use browser features, you can completely hide them by setting **Settings > Advanced > Enable browser-style profiles** to **No**. ## Core Features ### Navigation and Window Management - Browser profiles work within iTerm2's standard window/tab/split pane hierarchy. - Use hotkey windows, Open Quickly, navigation shortcuts, and per-session hotkeys as with terminal sessions. - **Exception:** ⌘-[ and ⌘-] perform Back/Forward navigation instead of pane switching in browser sessions. - **Cmd+click** opens links in new tabs. - **Cmd+Shift+click** opens links in new vertical split panes. - **Cmd+Shift+Option+click** opens links in new horizontal split panes. ### Text and Selection - **Copy on selection** works identically to terminal windows. - **Smart Selection** works identically to terminal windows. Smart Selection Actions appear in the context menu. - **Copy Mode** uses the same keystrokes as terminal sessions. - **Jump to Selection** functions as in terminal sessions. - **Find** supports regular expressions and case-sensitive search, just like in a terminal. ### AI Integration - Link browser sessions to AI chat to discuss web pages. - Click hamburger menu → **Ask AI** to create a new AI chat with the reader-mode content of the current page attached. - Summarize, analyze, or ask questions about the current page. ### Privacy and Security - **/dev/null mode** is a mode for browsing privately that prevents any data from being saved to disk. - Built-in popup blocking blocks popups not initiated by user action. - Simple ad blocking using WebKit content blocker rules (configure via hamburger menu → **Settings**). - CONNECT proxy support for proxy-based adblockers. - The existing password manager has been integrated. Browser passwords are stored separately from terminal passwords. - Password manager integration for 1Password, and LastPass will use your existing web passwords. ### Remote Access - View files on remote hosts via SSH Integration using URLs like: `iterm2-ssh://example.com/home/user/file.jpg` ## Advanced Features ### Bookmarks and Organization - **Named Marks** act as bookmarks for specific page sections (right-click → Add Named Mark). - Standard bookmarks available via hamburger menu. - Named Marks and Bookmarks work with Open Quickly and the Named Marks Toolbelt tool. ### Recording and History - **Instant Replay** captures browser sessions using macOS Screen Capture API. - Like instant replay in terminal windows, the RAM limit is respected. - **Global Search** can search across browser sessions. ### Automation and Customization - **Key Bindings** work in browser profiles (some terminal-specific actions are unavailable). - **Triggers** match when pages finish loading with web-specific actions. - **Pointer bindings** and **Actions** available, minus some terminal-specific options. - **Snippets** insert text into a focused form field. - **Broadcast Input** works across browser sessions. - **Advanced Paste** available, minus some terminal-specific features. - **Composer** functions in browser sessions. ### Content Management - **Reader Mode** is avilable in the hamburger menu. - **Distraction removal mode** similar to Safari's is also in the hamburger menu. - Right-click → **Remove Element** to hide cookie panels or other unwanted elements. - **Shell > Save Contents** saves web pages with resources. - Basic auto-fill of form fields is available, using your contact card information. - Search suggestions in URL bar. - Automatic audio detection and muting. ## Technical Details The browser is built on WKWebView and identifies as Safari to ensure compatibility with most websites. ## Limitations - **Python API** No browser-specific APIs yet. [File a feature request](https://iterm2.com/bugs) if you have ideas. - **Passkeys** Not supported due to Apple-imposed WKWebView restrictions. - **Advanced ad blocking:** Limited by Apple's resource fetching API restrictions. ## About This Feature This feature exists because: - Many iTerm2 features translate well to web browsing - It provides a unified terminal and browser experience - A former colleague suggested this idea in 2014 and I haven't been able to stop thinking about it. - I am maybe having a midlife crisis and this is cheaper than a sports car. While not intended as a primary browser, iTerm2's web capabilities provide a useful tool for integrated terminal and web workflows.