iTerm2 should require little explanation for users accustomed to terminal emulators. Even if you are an experienced user, take the time to read through the highlights section of this document. It will familiarize you with some features of iTerm2 that you may not have seen in other terminal emulators that can make a real difference in the way you work. Show
If you're having problems, please use the Bug Reporter. Table of Contents
Introduction User Interface Features Scripting Advanced Highlights for New UsersThis chapter describes features of iTerm2 that go beyond basic usage and are not generally found in other terminal emulators. Text SelectionThere are several ways to select text to copy to the clipboard:
Split PanesiTerm2 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 WindowiTerm2 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. Swap Cmd and OptioniTerm2 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 Preferences > 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 MarkYou 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 SearchWhen 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 is used. AutocompleteAny 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 HistoryWhenever 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 Preferences > General > Save copy/paste history to disk. Instant ReplaySometimes 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 Preferences > 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 ScreenYou 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 Preferences > General > Native full screen windows. High-Color ModesiTerm2 supports 256 color mode. To enable this for csh shells, set your terminal to xterm-256color (under Preferences > Profiles > Terminal > Report Terminal Type). Some applications may need to be configured to support this mode. In vim, add this to your .vimrc:
iTerm2 also supports 24-bit color. Focus Follows MouseThis option is off by default, but can be enabled under Preferences > Pointer > Focus follows mouse. It only affects iTerm2 windows. Middle Button PasteIf 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 FineryWhen 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 Preferences > 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 Preferences > 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 Preferences > Profiles > Colors > Cursor Guide. This can also be toggled by an escape sequence. For example, add this to your .vimrc:
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 ContrastSometimes 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 Preferences > 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 SupportIf you enable notifications (Preferences > 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 to send a notification. You can adjust the kinds of notifications that get posted in Preferences > Profiles > Terminal > Filter Alerts. Window ArrangementsYou 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 Preferences > General > Open saved window arrangement. Smart SelectionPerforming 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. TriggersTriggers 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 manual. Tmux IntegrationiTerm2 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 document. CoprocessesCoprocesses 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 document. Dynamic ProfilesIf you have hundreds or thousands of profiles, look in to Dynamic Profiles. This feature allows you to define profiles in JSON. Automatic Profile SwitchingYou can automatically change the current session's profile using Automatic Profile Switching. For example, this would allow you to change the background color when you are on a production system. Inline ImagesiTerm2 can display images inline, including animated GIFs. The easiest way to use this feature is to install Shell Integration and Utilities, which adds an Undo CloseIf you accidentally close a session, you get five seconds (by default; configurable in Preferences > Profiles > Session) to undo it by pressing Cmd-Z. Shell IntegrationShell 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 for all the details. Password ManageriTerm2 can save your passwords in the Keychain. Use the Window > Password Manager menu item to open the password manager and enter your passwords. TimestampsToggle 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 LeftYou 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 QuicklyIf 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 UtilitiesShell 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. 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. Python Scripting APIiTerm2 can be customized with its Python API. Status BarYou can configure a status bar to show information about your environment at the top or bottom of the window. General UsageTabsWhen 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 out is being received. When the session ends, a ⃠ icon appears in the tab. You can customize these indicators in Preferences > Appearance. Edit Current SessionThe 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. PointerThe 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 Preferences > Pointer. I recommend using three-finger tap for smart selection, but you must ensure that System Preferences > 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 noncontinguous 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, or if you have Shell Integration installed. If you hold cmd and option while selecting, a rectangular selection will be made. If mouse reporting is enabled (in Preferences > 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:
You can configure your pointing device's scroll gesture to send arrow keys in interactive programs by turning on Preferences > Advanced > Scroll wheel sends arrow keys when in alternate screen mode, but it will only work if Preferences > 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. KeyboardEvery aspect of the keyboard can be configured in iTerm2. These keystrokes may be useful to remember:
You can configure any key combination to perform any action in two places: in Preferences > Keys, you can define global key shortcuts that affect all profiles. In Preferences > 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 Preferences > 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. Context menusBy 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. ProfilesMany 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. General PreferencesGeneralStartupWindow restoration policyThis setting determines how windows will be opened when iTerm2 is launched. Most users will want Use System Window Restoration Setting as it works best with Session Restoration. Users who exclusively use the Hotkey Window may prefer Only Restore Hotkey Window, which will not restore regular windows but will restore the hotkey window. If you have a default window arrangement saved then Open Default Window Arrangement will be available. Open profiles windowIf selected, the Profiles Window will automatically open when iTerm2 is started. ClosingQuit when all windows are closedIf selected, iTerm2 will automatically quit when its last terminal window is closed. Confirm closing multiple sessionsIf selected, commands that close one session will not be confirmed, but commands that close multiple sessions (such as clicking the red button on a window with two or more tabs) will be confirmed with an alert box. Confirm Quit iTerm2 CommandIf selected, the Quit iTerm2 (cmd-Q) command will be confirmed if any terminal windows are open. Even if there are no windowsModifies Confirm Quit iTerm2 COmmand to disable the prompt when there are no open windows. MagicInstant Replay Uses X MB per SessionThis setting specifies the maximum amount of memory allocated to instant replay for each tab or split pane. More memory means instant replay is able to go farther back into the past. You can enter instant replay with View > Step Back in Time. Save copy/paste and command history to diskIf selected, every time text is copied or pasted in iTerm2 it will be saved to disk. The last 20 values are recorded. They can be accessed with Edit > Open Paste History.... If you use Shell Integration then when this is enabled your command history, directory history, and remote hostname and usernames will also be saved to disk. Unchecking this will erase all of the saved information. Enable Python APIToggles the availability of the Pythono API. See Python API Authentication for details on the security model. GPU RenderingThe GPU renderer improves drawing performance, but it may use more energy. You can also configure when it is enabled in Advanced GPU Settings. The advanced settings are:
ServicesAdd Bonjour hosts to profilesIf selected, all Bonjour hosts on the local network have a profile created for them as long as they're around. Check for updates automaticallyIf enabled, iTerm2 will periodically check if a new version of iTerm2 exists, and if so it will prompt you to download and upgrade. Prompt for test-release updatesIf enabled, iTerm2 will periodically check if a new unstable version of iTerm2 exists, and if so it will prompt you to download and upgrade. SelectionCopy to pasteboard on selectionIf enabled, text is copied to the clipboard immediately upon selection. If not selected, you must select Edit > Copy to copy it. Copied text includes trailing newlineIf enabled, a terminal newline will be copied to the pasteboard when the selection includes one; otherwise, no selection will ever include a terminal newline. Applications in terminal may access clipboardIf enabled, clipboard access will be granted via escape code to programs running in iTerm2. They will be able to set the contents of the system pasteboard. For more details, see Shell Integration Utilities. Triple-click selects full wrapped linesIf enabled, a triple click selects a whole line, even if it was longer than one row in the terminal. If off, then triple click selects exactly one row. Double-click performs smart selectionIf enabled, double click performs smart selection instead of word selection as is standard on macOS. Automatically enter copy mode on Shift+Arrow Key with selectionIf enabled, pressing shift-left or shift-right will enter copy mode when a selection exists. Characters considered part of a word for selectionWhen you double-click in the terminal window, a "word" is selected. The OS's algorithm for word selection is used, but it's extended to also include characters in this set. For example, by adding WindowSmart window placementIf enabled, new windows will be opened where they least overlap existing windows. Adjust window when changing font sizeIf enabled, a change to a session's font will cause the window to grow or shrink. Zoom button maximizes vertically onlyIf enabled, the green "Zoom" button expands a terminal window vertically but does not affect its width. This can be overridden by holding down shift while clicking the zoom button. Native full screen windowsIf enabled, fullscreen windows will animate into a special desktop, as is typical in macOS 10.7 and later. If disabled, fullscreen windows will instantly go fullscreen without changing desktops. Separate window title per tabThe OSC 0 and OSC 2 control sequences set the window title. This setting controls whether such a control sequence changes the window title associated with all sessions in the window, or only with the one in which it was received. PreferencesLoad preferences from a custom folder or URL:If enabled, iTerm2 will load its preferences from the specified folder or URL. After setting this, you'll be prompted when you quit iTerm2 if you'd like to save changes to the folder. Save changes to folder when iTerm2 quitsWhen you've turned on Load preferences from a custom folder and this is on then any changes you make to your settings will be written to the custom folder. tmuxWhen attaching, restore windows as…The first dropdown box in the tmux Integration section allows you to define how tmux windows should be mapped to native constructs. When attaching to a new tmux session with the tmux integration, tmux windows not seen by iTerm2 before will open in either new windows or tabs, as specified by this preference. Automatically bury the tmux client session after connectingWhen the tmux integration is entered by running tmux -CC, the window in which that command was run will be buried. Use "tmux" profile rather than profile of connecting sessionThis used to on by default, but is no longer so as of version 3.3. When enabled, a copy of the Default profile is created, called When disabled, the profile of the session in which you ran Status bar shows tmux status bar content, not native components.When enabled, the status bar will contain the same content as the tmux status bar in its text-mode UI. When disabled, the status bar defined in the profile used for a tmux integration session will be used. Pause a pane if it would take more than X seconds to catch up.When both a tmux integration and tmux text-mode UI client are attached to the same tmux session, the text-mode UI can sink data much faster than tmux integration can because it drops information between frames. In this case, a large buffer can grow in the tmux integration window. Once the time to catch up exceeds this number of seconds, the tmux integration session will be paused. That means it stops receiving new data. While paused, no more data will be added to its buffer and may be lost forever. You will be prompted by a notification at the top of the window to unpause the session. This feature is only available in tmux 3.2 and later. Warn Before PausingIf enabled, a notification is shown when a pause is projected to occur within half of the pause deadline. See Pause a pane if it would take more than X seconds to catch up for more detail on pausing. Unpause AutomaticallyWhen enabled, this unpauses the tmux session as quickly as possible after it is paused by tmux. It does not completely eliminate the possibility of data loss. Appearance PreferencesAppearanceGeneralThemeAllows you to select the theme. The theme affects how the areas outside the main terminal view are drawn, including colors and fonts. On macOS 10.13 and earlier, the options are Light, Dark, Light High Contrast, and Dark High Contrast. On macOS 10.14 and later, there are two additional options:
In Minimal and Compact, tabs go in the title bar if the tabs are on top. The area between the red, yellow, and green buttons and the first tab can be used to drag the window. If tabs are on the bottom or the left, you can move the mouse to the top left of the window to reveal the red, yellow, and green buts. The area around them, when revealed, can be used to drag the window. Tab Bar LocationDefines whether tabs appear at the top, bottom, or left side of your windows. Status Bar LocationDefines where the status bar appears, if enabled. Auto-hide menu bar in non-native fullscreenWhen native fullscreen mode is disabled (in Prefs > General), this option is available. If you'd like the menu bar to remain visible when a fullscreen window is present on a screen with a menu bar, turn this on. Exclude from Dock and Cmd-Tab Application SwitcherWhen this setting is enabled, iTerm2 will disappear from the dock and you won't be able to switch to it with Cmd-Tab. An icon will be added to the right side of the menu bar that lets you get back to iTerm2's preferences. This is useful if you only use hotkey windows and you want iTerm2 to keep a low profile. WindowsShow window number in title barIf selected, window titles include the window number. You can navigate to a window by pressing cmd-opt-N where N is the window number. You can also change which modifiers are used in Preferences > Keys. Show border around windowIf selected, a 1-pixel border will be shown around the edges of terminal windows. On macOS 10.14, window borders are only drawn for windows with some transparency. Opaque windows get a border drawn by the OS. Hide scrollbarsIf selected, scrollbars will be hidden in terminal windows. Disable transparency for fullscreen windows by defaultIf enabled, entering fullscreen mode will automatically turn off transparency for that window. Show line under title bar when tab bar is not visibleTurn this off for a sleek appearance with the dark theme. Show proxy icon in window title barWhen enabled, an icon representing the current directory is added to the window's title bar. You can drag it. TabsShow tab bar even when there is only one tabIf selected, the tab bar will remain visible when a window contains exactly one tab. Preserve window size when tab bar shows or hidesWhen enabled, the window will not change size as the tab bar is shown or hidden. Instead, the number of rows of text inside the window may change. Show tab numbersIf selected, tabs will indicate their keyboard shortcut. Show tab close buttonsIf selected, tabs show close buttons. If not selected, the close buttons only appear when the mouse hovers over the tab. Show activity indicatorIf selected, the activity indicator in each tab will be displayed when new output is recevied and the tab is not selected. Show new-output indicatorIf selected, non-selected tabs will indicate they have unseen output with a blue circle in the tab. Flash tab bar when switching tabs in fullscreenIf selected, the tab bar will show briefly when switching tabs in a fullscreen window. It will also show briefly when the number of tabs changes. Show tab bar in fullscreenIf selected the tab bar will be visible in fullscreen windows. Stretch tabs to fill barIf selected, tabs will grow large enough to fill the entire tab bar, like system native tab bars. This is on by default. PanesShow per-pane title bar with split panesWhen a tab has split panes, this option controls whether each split pane will have its own title bar. Separate status bars per paneWhen enabled, each pane gets its own status bar. When disabled, the window has a single status bar that shows information pertaining to the current pane. Separate background images per paneWhen disabled, the current pane's background image fills the window, spanning all panes. DimmingDimming amountThis slider controls how much to dim inactive windows or panes. Dim inactive split panesIf selected, split panes that do not have keyboard focus will be slightly dimmed. Dim background windowsIf enabled, windows in the background (that is, those not receiving keyboard input) are dimmed according to the above settings. Dimming affects only text, not backgroundWhen a window or pane is dimmed, this option controls whether the background color is dimmed or only the text colors. General Profile PreferencesProfilesGeneralNameGives the name of the profile which is shown in menus, preferences, and the profiles window. This serves as the default session name for sessions created with this profile, which is an interpolated string. Shortcut keyThis shortcut can be used to open a new window or tab. By default, it opens a new tab, but if you hold down the option key while pressing the shortcut, a new window will be opened instead. TagsTags are a collection of words or phrases that annotate a profile. When you search your profiles (for instance, in the profiles window), the tag names are searched in addition to the profile name. If a tag name contains a slash that defines a hierarchy of menu items in the Profiles menu. BadgeThe badge is a large label visible in the top right of a terminal session behind its text. For more information see Badges. This is an interpolated string. Click the Edit... button to configure the position, maximum size, and typeface of the badge. IconYou may assign an icon to the profile, elect to use the built-in icon (which is based on the foreground application), or to have no icon at all. Icons appear in the tab bar and the window title bar. TitleThis menu contains items which may be separately enabled. They are combined to form the session's title. The session's title is shown in per-pane title bars, when visible; it is also the default tab title. The current tab title also serves as the window title. The standard items in this menu are:
If a script that installs a custom title provider is running, its offerings will be added to the bottom of the list. For a working demo, see the George's Title Algorithm example. Applications in terminal may change the titleWhen enabled, a control sequence can change a session's or window's title. CommandThis is the command that is executed when a new session with the profile is created. If login shell is chosen, then When custom shell is selected, you should enter the path to a shell (e.g., Send Text at StartThis text will be sent when a session begins. If it is not empty then a newline will be sent afterwards. It does not accept any special characters or require any escaping. Working directoryNormally, new sessions begin in your home directory. You can choose to open new sessions in the same directory as the current session (but only when creating a new tab), or you can specify a starting directory. URL SchemesYou can configure a profile to handle a URL scheme, such as ssh. When a hyperlink is clicked on with that scheme, a new tab is opened with the selected profile. It is recommended that you set the command to "$$", in which case an ssh command line will be auto-generated. For other schemes, you can uses these variables in the Command field and they will be replaced with the appropriate part of the URL:
Color Profile PreferencesProfilesColorsClicking on any of the color wells opens a color picker that lets you change the setting for the selected color. iTerm2 has a custom color picker. If you don't like it you can revert to the system color picker by clicking the rectangular icon to the right of the eyedropper. Smart cursor colorWhen selected, a block cursor will be displayed in reverse video. If this would result in confusion, then a different color is chosen that will be most visible given the surrounding cells' background colors. Minimum contrastIf text is displayed against a similar background color, the minimum contrast setting will move the text color towards black or towards white to ensure some minimum level of visibility. Setting this slider all the way to maximum will make all text black and white. Cursor BoostCursor Boost dims all colors other than the cursor colors to make the cursor stand out more. Tab ColorIf enabled, this color will decorate the tab control. Tabs indicate the color of their current session if there is more than one split pane. Underline ColorIf enabled, this color will be used for all underlining, independent of the color that underlined characters have themselves. Cursor GuideThe cursor guide is a horizontal rule that indicates the vertical position of the cursor. You can adjust its color, including alpha value, to make it more visible against your background color. Color Presets...iTerm2 ships with some color presets, which you may load from this popup menu. You can import and export color presets to files with the extension "itermcolors". There is an online color gallery where users may share color presets, and a link to it is provided in this menu. When importing a color preset, the name it is assigned is based on the filename imported. BoldWhen enabled, this color is used for bold text. Text Profile PreferencesProfilesTextCursorThis lets you select a cursor shape. Blinking cursorIf checked, the cursor will blink slowly to improve visibility. Draw bold text in bold fontIf selected, bold text will be drawn in a bold version of the selected font. If the font does not have a bold version, then a bold appearance is simulated by "double striking" the text: that is, drawing it twice, shifting it one pixel horizontally the second time. Blinking textIf selected, text with the blink attribute set will actually blink. Oh, the humanity. Italic textIf selected, text with the italic attribute set will be rendered in italics. The font you select must have an italic face. Use thin strokes for anti-aliased textAnti-aliased text will be drawn with thinner strokes by default on Retina displays when the background color is darker than the foreground color. The effect may be more or less visible depending on your particular hardware and OS version. You can configure when thin strokes are used depending on display type and colors. Use built-in Powerline glyphsWhen enabled, iTerm2 renders Powerline glyphs itself rather than using what is built-in to the font. These glyphs tend to line up better with other elements than font-provided glyphs. Enable subpixel anti-aliasing (macOS 10.14 and 10.15 only)When enabled, subpixel anti-aliasing is enabled throughout the application. You must restart iTerm2 for this to take effect. Subpixel anti-aliasing uses artifacts of LCD displays to improve the perceived resolution. Enabling this incurs a minor performance penalty for drawing operations. This is not available in macOS 11.0 and later because Apple has removed support for it. Use Unicode Version 9 WidthsUnicode version 9 offers better formatting for Emoji. If your applications have been updated to use these tables, you should enable this setting. Treat ambiguous-width characters as double widthSome characters (e.g., Chinese ideograms) are double-width, and take two cells to display. Other characters (e.g., Latin letters) are single width and take only one cell to display. There is another category of characters known as "ambiguous width". One example of ambiguous-width characters are Greek letters. Depending on your application, you may prefer to display them as double-width or single-width. If most of the text you deal with is double-width, then you should enable this setting as it will help things to line up correctly in that context. Unicode normalization formThis affects how text is processed on input. Most users will want no normalization. HFS+ normalization preserves the fullwidth attribute of composed characters. Regular fontASCII text (latin letters, numbers, and some symbols) will be drawn using this font. Select "Anti-aliased" to draw the text with smooth edges. Non-ASCII fontAll non-ASCII text (many accented Latin letters, non-Latin text, less-common symbols, and thousands of miscellaneous unicode characters) will be drawn with this font. It is recommended that you use the same point size for both regular and non-ASCII fonts. Select "Anti-aliased" to draw the text with smooth edges. LigaturesWhen enabled and you have a font that supports ligatures (such as FiraCode) then text will be rendered with ligatures. This makes drawing much slower for two reasons: first, it disables the GPU renderer. Second, it uses a slower API. Users on less-than-stellar hardware may not want to enable it. Window Profile PreferencesProfilesWindowTransparencyThis sets the transparency of the window background. It can be temporarily disabled with View > Use Transparency. Keep background colors opaqueIf selected, non-default background colors will be opaque. BlurIf selected, the window background is blurred provided the background has some transparency. Selecting a large radius will blur the background more, but (especially on Retina displays) comes with a performance penalty. Rows/ColumnsWhen creating a new window with this profile, it will be created with this many rows and columns. Hide after openingIf enabled, a window created with this profile will immediately miniaturize after its creation. Open ToolbeltIf enabled, a window created with this profile will feature an open toolbelt. Custom window titleNew windows created with this profile will use this title by default, overriding the default behavior of using the current tab's title as the window's title. This is an interpolated string. Force this profile to always open in a new window, never in a tab.If you ask for a new tab with this profile, it will just open in a window instead. This is for people who hate tabs. Use TransparencySets whether the transparency setting is respected for new windows created with this profile. It can then be toggled with View > Use Transparency. Background ImageThis allows you to select an image to display behind the terminal's text. ModeThis allows you to select how the image is scaled to fit the window:
See also: Preferences > Appearance > Panes > Separate background images per pane. Custom Tab TitleNew tabs created with this profile will use this tab title by default. This is an interpolated string. BlendingThe blending slider determines how strongly the image dominates over the text's background color. StyleThis defines the window style.
ScreenIf you have more than one screen connected, this lets you select the screen on which a new window should open. It is particularly useful for fullscreen and top-of-screen window styles. The Screen with Cursor option affects the initial screen of the window, but it won't follow your cursor from screen to screen. SpaceIf you have enabled Spaces (or your OS uses Desktops instead of spaces) and have set Spaces/Mission Control to use Control+Number to switch spaces/desktops, then you can use this setting to select the initial space/desktop to open a new window using this profile. Terminal Profile PreferencesProfilesTerminalScrollback linesThe number of lines of scrollback buffer to keep above the visible part of the screen. Unlimited scrollback will allow it to grow indefinitely, possibly using all available memory. Save lines to scrollback when an app status bar is presentSome programs (such as vim or tmux) keep a status bar at the bottom of the screen. For some applications (like vim) it is undesirable to save lines to the scrollback buffer when the application scrolls. For others (like tmux) you may want to save scrolled-off lines into the scrollback buffer. When this setting is enabled, lines scrolled off the top of the screen in the presence of a status bar are added to the scrollback buffer. The screen is considered to have a status bar if it has a scroll region whose top is the first line of the screen and whose bottom is above the bottom of the screen. Save lines to scrollback in alternate screen modeWhen in alternate screen mode, lines that scroll off the top of the screen will be saved to the scrollback buffer only if this option is enabled. Character encodingThe encoding to send and receive in. For most people, "Unicode (UTF-8)" is the right choice. Report terminal typeThe TERM variable will be set to this value by default. If xterm-256color is selected and your system is missing the terminfo file, you will be prompted to install it when you open a new session. ENQ answer backText to send when the ENQ sequence is received. Not normally used. Enable mouse reportingIf selected, applications may choose to receive information about the mouse. This can be temporarily disabled by holding down Option. Enable mouse wheel eventsIf disabled, the mouse will always perform its default action (such as scrolling history) rather than being reported to an app that has enabled mouse reporting. Terminal may report window titlePrograms running in a terminal may send an escape code to request the current window title. You may disable this feature by enabling this option. It should be disabled if you're communicating with an untrusted party, as there are possible injection attacks. Terminal may enable paste bracketingPaste bracketing is a feature that can be enabled by an app running in iTerm2 by sending a control sequence. When enabled, iTerm2 transmits a control sequence before and after paste operations (e.g., pressing Cmd-V). This can be useful because editors like vim may disable auto-indenting when pasting already-indented code. Sometimes paste bracketing can be left on, causing unexpected behavior when you paste. For example, if a program running in an ssh session enables paste bracketing and then your ssh connection ends unexpectedly it won't have a chance to turn it off. Your next paste will include the bracketing control sequences, which will be mishandled by whatever program receives them. For that reason, some people prefer to disable paste bracketing. If you install Shell Integration it can detect when this occurs and automatically disable paste bracketing for you, making it safe to leave it enabled here. Terminal may set tab/window titleIf enabled the terminal may set the window or tab title with an escape sequence. Disable session-initiated printingIf enabled, escape codes that initiate printing will be ignored. Disable save/restore alternate screenSome programs (such as vim, tmux, and less) switch into a so-called "alternate screen". A characteristic of this behavior is that when these programs terminate the screen's contents are restored to their state from before the program was run. If this option is selected, alternate screen mode is disabled and the screen cannot be restored by an application. Disable session-initiated window resizingIf the host sends an escape code to resize the window, it will be ignored if this option is selected.. Silence bellIf selected, the bell (control-G) will not make an audible sound. Send Notification Center alertsIf selectedinstalled, iTerm2 will post a notifications when sessions receive output, become idle, ring the bell, close, or get a proprietary escape sequence to post a notification. Filter AlertsThis button opens a panel that lets you customize which notifications will be posted. Flash visual bellIf selected, a bell graphic will be flashed when the bell character is received. Show bell icon in tabsIf selected, tabs will indicate that a bell has rung by displaying a bell graphic. Set locale variables automaticallyIf enabled, LANG and LC_CTYPE environment variables will be set based on your machine's language settings. Insert newline before start of command prompt if neededIf you have Shell Integration installed and a command's output does not end in a newline, this setting will ensure your prompt does not begin in the middle of the line. Show mark indicatorsIf you have Shell Integration and this setting is selected then a blue or red arrow appears next to each shell prompt. Turn this off to hide the arrow. Session Profile PreferencesProfilesSessionAutomatically close a session when it endsIf selected, a session's pane, tab, or window will automatically close when the session ends. "Undo" can revive a session that has been closed for up to X secondsWhen you close a session, window, or tab the shell is not terminated until X seconds pass. While that time period has not elapsed, Undo will reopen the session, tab, or window. Prompt before closingWhen a session will close, you can choose when to be prompted with a modal alert. Automatically log session input to files in:If enabled, every session's output will be logged to a file in the specified directory. File names are formatted as Date_Time.ProfileName.TerminalID.ProcessId.RandomNumber.log. You can customize the filename in Preferences > Advanced > Format for automatic session log filenames. Log plain textWhen enabled, control sequences will be stripped out before logging. This will produce confusing output when an interactive application like emacs is used, but for simple command-line interactions it produces a more usable log file. When idle, send ASCII code X every Y seconds.If selected, the specified ASCII code "X" (a number from 0 to 255) will be transmitted every Y seconds while nothing is happening. Don't use this unless you know what you're doing as it can have unexpected consequences. Seriously, it's probably not what you want. Avoid repainting while cursor is hidden to reduce flicker while scrollingWhen selected, the screen will slightly delay redraws while the cursor is hidden. This improves the visual appearance of scrolling in many programs but might introduce noticeable delays for some users. Status bar enabledSee Status Bar for details on the status bar. Keys Profile PreferencesProfilesKeysThis panel shows key mappings. You can double-click on a mapping to edit it. When the "Keyboard Shortcut" field has focus, you should press the keystroke that you want to modify (even if it involves modifiers like Cmd). The following actions are available:
You can add a new keymapping by pressing "+". You can remove an existing mapping by selecting it and pressing "-". Three presets are provided: "Xterm defaults" is the normal key mappings, while "Xterm defaults with numeric keypad" disables the "application keypad" in favor of the numbers and symbols that the numeric keypad typically emits. "Terminal.app Compatibility" tries to emulate the way that Terminal.app sends keys by default. Delete sends ^HIf you are on a legacy system that does not accept ^? for backspace, select this and it will add a key mapping for you. Allow Application Keypad ModeSome full-screen progarms (like emacs) switch the keyboard into application keypad mode, which changes how the numeric keypad behaves. Disabling this option causes iTerm2 to never enter application keypad mode. Report modifiers using CSI uEnables a more powerful keyboard reporting algorithm that some applications may use to enable the use of modifiers on more keys and more combinations of modifiers. Left/Right Option Key Acts AsIt is common to use a modifier to send so-called "meta keys". For most users, selecting "+Esc" here is the right choice. The "Meta" option sets the high bit of the input character, and is not compatible with modern systems. A hotkey opens a dedicated window with this profileWhen enabled, a dedicated hotkey window is attached to this profile. The Configure Hotkey Window button lets you configure the hotkey and other attributes of the window. For more information, see Hotkey Windows. Advanced Profile PreferencesProfiles > AdvancedTriggersTriggers are actions that are performed when text matching a regular expression is received. Each trigger has a regular expression, which defines when it runs. It has an action, which defines what it performs, and it has an optional parameter, whose meaning depends on the action. When the parameter is textual, \0 is replaced with the entire match, and \1...\9 are replaced with match groups. Each trigger has a checkbox in the "Instant" column. Instant triggers run as soon as text matching the regular expression is matched; triggers that are not instant only match after the cursor moves off the current line (such as whena newline is received). Full details can be found at Triggers. Semantic HistorySemantic history is used to open a file when you Cmd-Click on it. The current working directory for each line in the terminal is tracked to help find files. If Semantic History is set to "Open with default app," then files are passed to the OS to be opened with whatever is associated. Alternatively, you can choose "Open URL..." to open a specific URL (with \1 replaced with the filename and \2 replaced with the line number, if applicable). If you choose "Open with editor..." then text files will be opened with the designated editor, while other files are opened with the default app for their file type. For more flexibility, choose "Run command..." and specify a command to execute. \1 will be replaced with the file name, \2 will be replaced with the line number (if applicable), \3 with text in the line prior to the click location, \4 with text in the line subsequent to the click location, and \5 for the working directory of the line clicked on. Finally, "Always run command..." is like "Run command...," but takes effect even if the object clicked on is not an existing filename. Automatic Profile SwitchingYou can specify rules that, when satisified, changes any session's profile to this one. See Automatic Profile Switching for all the details. Keys PreferencesKeysKey BindingsThis interface works like the keyboard shortcut system in profiles (described above) but it affects all profiles. Settings here are overridden by those in a profile's key mappings. See the list of key binding actions at Preferences > Profiles > Keys. Add Touch Bar ItemThis button is only visible if your OS version supports touch bars. By pressing this button, you can define a new custom touch bar button with any of the actions you can assign to a key (see below). You can then add the custom button to your touch bar with View > Customize Touch Bar. Touch Bar MitigationsThis opens a panel with these options:
Navigation ShortcutsShortcut to activate a tabTabs are normally navigated with cmd+number, but you can change the modifier used for that function here. Shortcut to activate a windowWindows are normally navigated with cmd+opt+number, but you can change the modifier used for that function here. Shortcut to choose a split paneYou can use this to configure a modifier+number shortcut to select a split pane in the current tab. Emulate US KeyboardIf your keyboard layout requires you to hold Shift (or some other modifier) to press a number, enable this to treat the top row of keys as number keys even when Shift is not pressed. This only affects switching panes, tabs, and windows by keyboard as configure in the preceding settings. HotkeyCreate a Dedicated Hotkey WIndowSets up a new hotkey window profile if you don't already have one. For more information, see Hotkey Windows. Show/Hide iTerm2 all windows with a system-wide hotkeyWhen enabled, you can focus the Hotkey: field and press a keystroke. From then on, pressing that keystroke (even when iTerm2 is not the front application) will cause iTerm2 to come to the front. If it is the foreground app, it will be sent to the back. This requires that you enable access for assistive devices in the Universal Access panel of System Preferences. For more information, see Hotkey Windows. Remap ModifiersiTerm2 allows you to change the meanings of the modifier keys only within iTerm2. This is useful, for example, if you find it difficult to press "option" for "meta" and would prefer to use "command" for that purpose. Global shortcut keysArrangement PreferencesArrangementsThis tab lets you view saved window arrangements. You can delete them with the minus button and select the default arrangement. Pointer PreferencesPointerGeneralCmd-Click Opens Filename/URLIf enabled, then clicking on a filename (of an existing file on the local machine) or a URL will open it. Ctrl-click reported to apps, does not open menuIf enabled, ctrl-click will be sent to applications that support Xterm mouse reporting (if mouse reporting is enabled). Option-Click moves cursorIf enabled, option-click will move the cursor to where the mouse pointer is. If you install shell integration, this will be well-behaved at the shell prompt by not sending up and down arrow keys. Three-finger tap reports middle click to appsIf enabled, a three-finger tap acts like a middle click for the purposes of mouse reporting. Focus follows mouseIf enabled, moving the mouse over an inactive window will cause it to receive keyboard focus. Focus window after right or middle clickWhen enabled, right-clicking or middle-clicking on a window will give it keyboard focus. BindingsMouse Button and Trackpad Gesture ActionsYou may assign custom actions to mouse clicks and trackpad gestures. The left mouse button is not configurable because its behavior is rather complex, however. This is especially useful if you have a mouse with many buttons. Any combination of mouse button + number of clicks + modifiers may be assigned an action. For gestures, three finger taps and swipes may be configured in combination with modifiers. The following actions are available:
Advanced PreferencesAdvancedAdvanced preferences are self-documenting. Use the search field to find what you're looking for, as there are quite a few of them. ScriptingDeprecation WarningApplescript in iTerm2 is deprecated. It will continue to receive bug fixes, but new features will not be added. Please see the Python API docs for a much better alternative. Note: Applescript support is in maintenance mode. New code should use the Python API if possible. ApplescriptiTerm2 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. 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 ScriptsiTerm2 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 ScriptsiTerm2 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. ReferenceObjectsThe 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. ApplicationThe application exposes various properties and provides functions that are described in this section. For example:
Bridges to Python APIinvoke API expression "expression" Example:
launch API script named "name" Example:
Other Application-Level Actionscreate hotkey window with profile "name" Example:
create window with default profile 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 Examples:
create window with profile "name" 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 Returns a reference to the new window. Examples:
current window A reference to the window that most recently had keyboard focus.
windows A
WindowsThese functions and properties are provided by windows. For example:
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 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 tab The 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 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. SessionsThese functions and properties are provided by sessions. For example:
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:
An example:
Because Applescript is kind of a dumpster fire, the standard syntax for a color is answerback string The string sent when the 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 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 Changes the size of the session. split horizontally with default profile 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" Like the "default profile" commands, but uses a named profile instead of the default profile. split horizontally with same profile 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 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" Gets and sets the value of a variable by name. Variables are described in Scripting Fundamentals. You may only set user-defined variables, whose names always
begin with write text "text" 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. TabsThese functions and properties are provided by tabs. For example:
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 iTerm2If 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 Applescript ExamplesThis is an example of the Applescript syntax available in version 3.0 and later. Note: Applescript support is no longer receiving improvements. Use the Python API instead. tell application iTerm2 -- application-level commands -- These commands return a window. set newWindow to (create window with default profile) set newWindow to (create window with default profile command "ls -l -R /") Supporting both old and new versions of iTerm2If 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 Legacy NoteNote: in iTerm2 3.0.0, sessions had a property called contents. That conflicted with a reserved word, and has been renamed to text. The example below reflects proper usage for version 3.0.1 and up. Buried SessionsA 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. 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. Copy ModeCopy 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 Shift+Arrow key 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
Basic Movement
Content-Based Movement
Screen Movement
Line Movement
Document Movement
Other Commands
Menu ItemsiTerm2 MenuiTerm2 > Show Tip of the DayWhen 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 UpdatesChecks to see if a new version of iTerm2 is available. If Preferences > General > Prompt for test-release updates is turned on then this includes beta versions; otherwise only stable versions are downloaded. iTerm2 > Toggle Debug LoggingThis saves helpful debugging information in memory. When it is toggled off it is saved to /tmp/debuglog.txt. iTerm2 > Copy Performance StatsThis copies information about drawing speed to the pasteboard. This is useful when reporting issues relating to poor performance. iTerm2 > Capture GPU FrameThis 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 EntryWhen 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 TermMakes iTerm2 the default terminal for opening .command, .tool, .zsh, .csh, and .pl files. iTerm2 > Make Terminal Default TermYou 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 IntegrationThis opens a window that guides you through the installation of the Shell Integration features. Shell MenuShell > New Window/TabThis 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 Tab with Current ProfileThis creates a new tab using the same profile as the current session rather than the default profile. Shell > Duplicate TabCreates another tab with the same arrangement of split panes, profile, etc. Shell > Split Vertically/HorizontallyThese 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 ProfileThese 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 Selected TextSaves the selected text to a file. Shell > CloseTerminates the current session. Shell > Close Terminal WindowTerminates all sessions in the current window. Shell > Close All Panes in TabTerminates all sessions in the current tab. Shell > Broadcast Input > ...These options allow you to send keyboard input to more than one session. Be careful.
Shell > tmux > ...These commands let you interact with the tmux integration
Edit MenuEdit > Undo Close Session/Tab/WindowAfter you close a session, tab, or window then you have five seconds to undo it. The amount of time is configurable in PReferences > 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 SequencesCopies 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 ModeEnters Copy Mode which lets you make selections using the keyboard. See Copy Mode for details. Edit > Paste Special > Advanced PasteThis 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 SelectionPastes the currently selected text (which may differ from the text in the pasteboard). Edit > Paste Special > Paste File Base64-EncodedIf 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 Escaping Special Characters"Paste Escaping Special Characters" pastes the current string in the clipboard, but places a backslash before spaces and backslashes. 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/SlowerAdjusts the speed of pasting to be faster or slower. Edit > Paste Special > Paste Slowly Faster/SlowerAdjusts 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 PasteWhen enabled, you'll be warned before pasting more than one line. Edit > Paste Special > Limit Multi-Line Paste To Shell PromptIf 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 > Warn Before Pasting One Line Ending in a Newline at Shell PromptThis 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 > SnippetsGives access to Snippets, which are saved bits of text that can be pasted quickly. You can change snippets in Prefs>Shortcuts>Snippets. Edit > ActionsGives 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 > Selection Respects Soft BoundariesWhen enabled, vertical lines of pipe characters Edit > Select Output of Last CommandRequires shell integration to be installed. Selects the output of the last command. Edit > Select Current CommandRequires shell integration to be installed. Selects the text of the current command entered at the command prompt. Edit > Find > FindOpens 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/PreviousNote that the direction of next and previous is reversed relative to the standard macOS search direction. If you prefer for Next to mean down and Previous to mean up, set Preferences>Advanced>Swap Find Next and Find Previous to No. Edit > Find > Find GloballyOpens a window that lets you search all tabs at once. Edit > Find > Find URLsSearches the current session for URLish looking strings. Edit > Marks and Annotations > Set MarkRecords the current scroll position. Use Edit > Jump to Mark to restore the scroll position. Edit > Marks and Annotations > Add Annotation at CursorAdds 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 > Jump to MarkScrolls to the location of the last mark. Edit > Marks and Annotations > Alerts > Alert on Next MarkWhen a mark is set (typically by Shell Integration when the currently running shell command terminates) then show an alert. Edit > Clear BufferClears the entire terminal history and the mutable area. Edit > Clear Scrollback BufferClears scrollback history, preserving the mutable area. View MenuView > Show Tabs in FullscreenIf enabled, tabs are shown in fullscreen windows. View > Toggle Full ScreenEnters 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 Preferences > General > Native full screen windows. View > Use TransparencyThis toggles transparency. It only has an effect if you have configured your session to be transparent under Preferences > 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 > Zoom In on SelectionWhen 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 OutExits the Zoom In on Selection mode. View > Find CursorReveals the current cursor position. View > Show Cursor GuideToggles the visiblity of the cursor guide which is a horizontal rule showing the location of the cursor. View > Show TimestampsIndicate the time of last modification of each line on the screen. View > Show AnnotationsToggles the visibility of annotations. View > ComposerOpens a view that lets you edit a command before sending it. View > Auto Command CompletionAutomatically shows a window with command completion suggestions as you type. Only usable when you have command history built up with Shell Integration. View > Open QuicklyIf 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, open arrangements, and change the color preset. 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. /c restricts the results to color presets. View > Maximize Active PaneWhen 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 ProfileWhen enabled, changes made to the text size in this session (by selecting Make Text Bigger/Smaller) will be reflected in its profile. View > Start Instant ReplayStepping 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 Preferences > Instant Replay uses xx MB per session. The more memory you assign, the further back in time you can step. The instant replay UI also lets you choose to export a section of your terminal history to share with other iTerm2 users. View > Tab ColorAllows you to select a tint color for the tab, to make it easier to distinguish. You can also change the tab color in Profiles > Preferences > Colors. Session MenuSession > Edit SessionThis 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 CoprocessAllows you to start and stop a coprocess linked to the current session. Learn more about coprocesses. Session > Restart SessionAfter 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 > Open Autocomplete...Shows the autocomplete window, which offers to finish typing a word that you've begun. Learn more about autocomplete on highlights page. Session > Open Command History...If you use Shell Integration then Open Command History presents a list of recently used commands to select from. Session > Open Recent Directories...If you use Shell Integration 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. Add TriggerAdds a trigger, defaulting to highlighting the currently selected text. Session > ResetResets 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 > Start/StopLogging saves all input received in a session to a file on disk. Session > Log > Import/Export Recording...The Instant Replay feature allows you to view the past window state. The import/export feature allows you to save that state to an Session > Terminal StateShows the internal state of the terminal emulator and lets you directly manipulate it. Session > Bury Session/Buried SessionsBuries or unburies a session. See Buried Sessions for details. Scripts MenuIf you have scripts located in Scripts in the Python ScriptsThe Manage submenu contains items to help you create and maintain Python scripts that use iTerm2's Python API. New Python ScriptUse this to create a new script. See the Python API Tutorial for details on how to use it. Open Python REPLCreates a window with a Python read-eval-print loop (REPL). This is meant for experimenting with iTerm2's Python API. You may be asked to download and install the Python Runtime before this window will open. See the REPL section of the tutorial for details. Manage DependenciesThis opens a window that lets you modify the dependencies and Python version of scripts using iTerm2's Python API. You can add or remove dependencies using pip3 through this UI, which is recommended because each script may have its own copy of the Python environment it uses. Check for Updated RuntimeChecks if a new version of the Python Runtime is available. It may contain bug fixes or new APIs. Reveal Scripts in FinderShows
the Import...Allows you to choose an exported script (with the Export...Allows you to export an existing script as an ConsoleThe console shows the running scripts, their logs, and the history of communication between the script and iTerm2. It also offers access to the Inspector, which lets you view variables in the various sessions, tabs, and windows. It also reveals registered functions. Both the console and the inspector are intended to be used as debugging tools for people working with scripts using iTerm2's Python API. Profiles MenuThis 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 AllOpens all profiles in tabs (or in windows, if Option is pressed). Toolbelt MenuToolbelt > Set Default WidthSaves the current window's toolbelt width as the default width for new windows' toolbelts. Toolbelt > ActionsThis toggles the visibility of the Actions tools. It has a list of user-defined actions (for example, send a canned string of text). The tool provides an interface for editing the actions as well as invoking them. Tolbelt > Captured OutputThis toggles the visibilty of the Captured Output tool. It shows captured output located with the Capture Output trigger. See Captured Output for more information. Toolbelt > Command HistoryThis toggles the visibility of the Command History tool. It shows recently used commands. You must install Shell Integration for this to know your command history. Toolbelt > Show ToolbeltThis toggles the visibility of the Toolbelt on the right side of all windows. Toolbelt > JobsThis toggles the visibility of the Jobs tool, which shows the running jobs in the current session, and allows you to send them signals. Toolbelt > NotesThis toggles the visibility of the Notes tool, which provides a freeform scratchpad in the toolbelt. Toolbelt > Paste HistoryThis toggles the visibility of the Paste History tool, which shows recently pasted strings in the toolbelt. Toolbelt > ProfilesThis toggles the visibility of the Profiles tool, which lets you select profiles to open new windows, tabs, and split panes. Toolbelt > Recent DirectoriesThis 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 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. Toolbelt > SnippetsThis toggles the snippets tool, which holds strings that can be pasted quickly. You can edit snippets in Prefs>Shortcuts>Snippets. Custom ToolsScripts using the Python API may register custom tools. Those will also appear in this menu. See the Asymmetric Broadcast Input script for a working example. Window MenuWindow > Save/Restore Window ArrangementThe current state and positions of windows, tabs, and spit panes is recorded and saved to disk with Save Window Arrangement. Restore Window Arrangement opens a new collection of windows having the saved state. You can automatically restore the arrangement in Preferences > General > Open saved window arrangement. Window > Restore Window Arrangement as TabsRestores the windows in the selected window arrangement as tabs in the current window. Window > Password ManagerOpens the password manager. Window > Edit Tab TitleAllows you to enter a tab title to override the default, which is the current session's title. This is an interpolated string. Window > Edit Window TitleAllows you to enter a window title to override the default, which is the current tab's title. This is an interpolated string. Window > Window StyleAllows you to modify the window style, for example by removing the title bar. HotkeysA 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 WindowsThis 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 Preferences > 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 HotkeysYou 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 WindowsA 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 Preferences > 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:
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. tmux IntegrationiTerm2 is integrated with tmux, allowing you to enjoy a native user interface with all the benefits of tmux's persistence. IntroductionNormally, 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:
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:
For everyone:
UsageYou 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:
When you run tmux -CC, what you'll see on that terminal is a menu: tmux mode started
In general, you don't need to run commands to perform the most common actions. The following iTerm2 actions affect tmux:
LimitationsThere are a few limitations of tmux integration which are related to the design of tmux.
ConfigurationCheck Preferences > 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 Preferences. Best PracticesFor practical tips on how to configure iTerm2 for use with tmux integration in the real world, please see tmux Integration Best Practices. Touch BarAs with many applications, you may customize the controls on the touch bar with View > Customize Touch Bar. The following controls are available: Man PageOpens the manpage for the command behind the cursor. Color PresetWhen selected, this opens a scrollable list of color presets. Choosing one changes the current terminal's colors to use the preset. Function KeysThere 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 and Utilities, 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 MarkThe 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 MarkNavigates to the next or previous mark. If you have Shell Integration installed, each command prompt inserts a mark, so the previous mark is usually the previous shell prompt. Autocomplete SuggestionsIf you have Shell Integration installed, iTerm2 can remember you command history. That history is used to make suggestions for commands, which appear in this touch bar control. StatusThe status touch bar control shows a user-configurable message. If you install Shell Integration and Utilities, 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.
PS1='\s-\v\$[$(~/.iterm2/it2setkeylabel set status \ "$(test -d .git && (git rev-parse --abbrev-ref HEAD) || (echo -n "Not a repo"))")] ' Custom ButtonsYou can define custom touch bar buttons in Prefs > Keys > Add Touch Bar Item. You can then add the item to you touch bar from View > Customize Touch Bar. Shell IntegrationiTerm2 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. How To Enable Shell IntegrationThe easiest way to install shell integration is to select the iTerm2>Install Shell Integration menu item. It will download and run a shell script as described below. You should do this on every host you ssh to as well as your local machine. The following shells are supported: tcsh, zsh, bash, and fish 2.3 or later. Contributions for other shells are most welcome. When you select the iTerm2>Install Shell Integration menu item, it types this for you: curl -L https://iterm2.com/shell_integration/install_shell_integration.sh | bash Don't care for piping curl to bash? Do it by hand. This is also what you must do if you use a shell that isn't your login shell. 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 source ~/.iterm2_shell_integration.bash Don't want to or can't install a login script? See the workaround at the end of this document using triggers. Elvish users: Diego Zamboni maintains a shell integration script for Elvish on Github. FeaturesShell Integration enables numerous features: MarksThese are saved locations in history. They make it easy to navigate to previous shell prompts or other locations of interest. 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" 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. How it worksShell Integration works by configuring your shell on each host you log into to send special escape codes that convey the following information:
How to use itMarksWhen 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 Alert on next markiTerm2 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 statusThe 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 scpYou 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 scpIf 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 historyWith 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 popupYou can view and search the command history with Session>Open Command History... (Shift-Cmd-;). AutocompleteCommands in command history are also added to Autocomplete (Cmd-;). If Preferences>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). ToolbeltA 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 CompletioniTerm2 will present command completion suggestions automatically when View>Auto Command Completion is selected. Recent DirectoriesWith 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" (frequency and recency of use). There are two places it is exposed in the UI: Recent Directories popupYou can view and search your recently and frequently used directories in Session>Open Recent Directories... (Cmd-Opt-/). ToolbeltA 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 SwitchingPlease see the documentation at Automatic Profile Switching. Shell Integration for rootIf 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 test $(whoami) == root && source "${HOME}/.iterm2_shell_integration.bash" The alternative is to use Triggers to emulate shell integration as described in the following section. TriggersFor some users, installing a login script on every host they connect to is not 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:
Use these triggers to tell iTerm2 your current username, hostname, and directory. Suppose you have a shell prompt that looks like this: [email protected]:/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: \[email protected]\2
Then create another trigger with the action Report Directory. This regular expression will extract the directory from the example prompt: ^\[email protected][\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. You can navigate from mark to mark with Cmd-Shift-Up/Down Arrow. 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 LimitationsShell Integration does not work with tmux or screen. A Note on SCPiTerm2 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, 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:
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:
The scp code is relatively new. If you are in a high-security environment, please keep this in mind. Smart SelectioniTerm2 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:
How do I Change Smart Selection Rules?Under Preferences>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. ActionsActions 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. Actions may open a file, open a URL, run a command, or start a coprocess. A cmd-click on text matching a smart selection rule will invoke the first rule. Regular ExpressionsRegular expressions conform to the ICU regular expressions rules. TriggersA trigger is an action that is performed when text matching some regular expression is received in a terminal session. How to Create a TriggerTo create a trigger, open the Preferences 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 ExpressionRegular expressions conform to the ICU regular expressions 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 Preferences > Number of screen lines to match against trigger regular expressions. ActionsThe following actions are available:
TricksIf you'd like to match more text than you highlight with the Highlight Text trigger, you can use look-behind and look-ahead assertions. Suppose you want to highlight the word "ipsum" only when it occurs in the phrase "lorem ipsum dolor". Then you would use this regex: (?<=lorem )ipsum(?= dolor) 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. The interpretation of the parameter depends on whether Use interpolated strings for parameters (at the bottom of the Triggers window) is enabled. When Use interpolated strings for parameters is off:
Regardless of the Use interpolated strings for parameters setting:
When Use interpolated for parameters is on, a local variable named
InstantWhen 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, Use interpolated strings for parametersPrior to version 3.3 of iTerm2, parameters could use backreferences like ExampleThe iTerm2-zmodem project demonstrates hooking up iTerm2 to zmodem upload and download. Known IssuesFor performance reasons, triggers evaluate only part of very long lines. If a line wraps to more than three visible lines trigger behavior will be nondeterminstic. You can adjust the window size in Preferences > Advanced > Number of screen lines to match against trigger regular expressions. Captured OutputiTerm2 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. 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. Shell Integration RequiredShell Integration 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. ExampleOne 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 TriggersCreate a Trigger 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 ToolbeltOpen 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 makeKick off the build by running make. It spits out thousands of lines of output. Step 4: Examine the Captued Output toolAny errors or warnings that appear in the compiler output will appear in the Captured Output tool. Step 5: Open the file containing the errorThe Trigger created in step 1 takes an optional parameter. It is a command for iTerm2 to exceute as a Coprocess 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:
Step 6: Check it off the listYou 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. NavigationCaptured 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 OutputYou can use the
FontsWhile 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 Preferences. You can also specify the a "non-ASCII" font in the Text panel of profile preferences. 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; ligatures are also not supported by the GPU renderer, which is also much faster than the legacy renderer. Inline ImagesiTerm2 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 Example: imgcatUsing the 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. ProtocoliTerm2 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. For file transfer and inline images, the code is: ESC ] 1337 ; File = [arguments] : base-64 encoded file contents ^G The arguments are formatted as
The width and height are given as a number followed by a unit, or the word "auto".
More on File TransfersBy omitting the If the file's size exceeds the declared size, the transfer may be canceled. This is a security measure to prevent a download gone wrong from using unbounded memory. Sample CodeSample code for displaying images may be found here. imglsProvides an augmented directory listing that includes a thumbnail of each image in a directory. imgcatDisplays one or more images inline at their full size. it2dlDownloads a file, but does not display it inline. dividerDraws a full-width, one line-tall graphical divider. BadgesA 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 Preferences>Profiles>General>Badge and it can be changed by an iTerm2-proprietary escape sequence. This value is an interpolated string, which means the badge can expose it can display the value of variables. Here is an example of a session with a badge indicating the current user and host name. Escape SequencesThe 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:
ColorThe badge's color may be set in Preferences>Profiles>Colors. The font and size can be adjusted by selecting Preferences>Profiles>General>Edit… next to the Badge field. Dynamic ProfilesDynamic Profiles is a feature that allows you to store your profiles in a file outside the usual macOS preferences 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. AvailabilityDynamic Profiles are available in iTerm2 2.9.20140923 and later. UsageWhen 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. 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 FormatA 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:
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 Preferences. Here is a fully formed (but minimal) Dynamic Profiles plist: { "Profiles": [ { "Name": "Example", "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958" } ] } EditingThe 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 preferences UI those changes will not be reflected in the property list. AttributesEvery 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:
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 ProfilesNormally, 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 Starting in version 3.4.9, { "Profiles": [ { "Name": "Example", "Guid": "ba19744f-6af3-434d-aaa6-0a48e0969958", "Dynamic Profile Parent Name": "Light Background" } ] } MinutiaeDynamic 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. TroubleshootingIf something goes wrong loading a Dynamic Profile, errors will be logged to Console.app. TriggersBy default, Highlight triggers save colors in a large inscrutable mess of a format. For dynamic profiles, you can use ExampleHere's an example for a common use case: a list of profiles for sshing 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", }, ] } Profile Search SyntaxWhen iTerm2 presents a list of profiles, it usually includes a search box. The search box uses a special syntax that letes you tailor your searches to quickly find what you're looking for. Searching ProfilesEach 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.
OperatorsYou may prefix a phrase in the search query with an operator to narrow your query. Only two operators are defined:
QuotingYou can require that two or more words occur in order by putting quotes in your query. For example:
AnchoringNormally, 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".
Combining FeaturesYou 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. Automatic Profile SwitchingiTerm2 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 RequiredYou must install Shell Integration 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 SyntaxIn Preferences>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 A hostname can be a DNS name, like The job name is the name of the executable. For example, "vim" or "bash". It must be prefixed with an
ampersand Additionally, a rule may be designated as sticky by beginning with a Some examples:
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:
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 ReversionAfter 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 ImplementationEach 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 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. TriggersSince 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 for details. TroubleshootingThere are a few ways things can go wrong. Please see the Why doesn't secure copy/automatic profile switching work? document for help diagnosing and fixing these issues. CoprocessesiTerm2 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:
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.
UsageA 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. TroubleshootingIf a coprocess fails you will receive a notification in the terminal window that gives you the option to view its output to stderr. Technical DetailsThe 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. Session RestorationSession 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 Notes
UtilitiesiTerm2 has a collection of shell scripts that help you take advantage of some of its unique features. When you install Shell Integration 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. Most of the utilities work without Shell Integration. ComponentsThe Utilities Package contains the following programs: imgcatThe It supports all standard image formats, including animated GIFs. Usage:
or
imglsLists the files in a directory with thumbnail previews for images. Usage:
it2attentionRequests attention. Can bounce the dock icon or show a fireworks animation at the application cursor position. Usage:
it2checkChecks if the terminal emulator is iTerm2. Example: it2check && echo This is iTerm2 || echo This is not iTerm2 it2copyCopies 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. it2dlThe it2getvarFetches a session variable. For information about variables, see Scripting Fundamentals. Example: it2getvar session.name it2setcolorConfigures iTerm2's colors. Usage:
For example: it2setcolor preset 'Light Background' it2setkeylabelConfigures touch bar function key labels. Usage: 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. it2ulUploads a file. Works over ssh. Usage: it2ul [destination [tar flags]] If given, the 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 it2universionSets 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: it2dlUsage: it2dl filename LocationThe Utilities Package places shell scripts in Proprietary Escape CodesiTerm2 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: The OSC command 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:
And this gets the foreground color:
For background and foreground respectively, the terminal will write back:
Where Anchor (OSC 8)VTE and iTerm2 support OSC 8 for defining hyperlinks, much like HTML's anchor tag.
If the url is absent then that ends the hyperlink. Typical usage would look like:
To open a link, hold Command and click the link. Note: in iTerm2 version 3.4 and later, if the URL has the Set cursor shape
where .vimrc to change cursor shape in insert mode:
This is derived from Konsole. Set MarkThe "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:
Steal FocusTo bring iTerm2 to the foreground:
Clear Scrollback HistoryTo erase the scrollback history:
Set current directoryTo inform iTerm2 of the current directory to help semantic history:
Post a notificationTo post a notification:
Change profileTo change the session's profile on the fly:
Copy to clipboardThere are three ways to copy text to the clipboard for reasons that have been lost to history. OSC 1337 CopyToClipboard This method allows you to copy to various macOS-specific pasteboards. This is probably not useful to you unless you have very specialized needs. It is also the worst in terms of backwards compatibility because other terminals will simply display the text you wished to copy. To place text in the pasteboard:
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 Copy This is an alternative to OSC 52. The implementation is a bit more efficient for very large values. You can place a string in the system's pasteboard with this sequence:
Where OSC 52 This is not a proprietary control sequence. It's probably your best choice since it'll work with other terminal emulators. To write to the pasteboard:
The In version 3.5 and later, iTerm2 supports the sequence to query the clipboard:
The clipboard contents are reported with:
Where Pc is the same as in the request. User consent is required both to read and write the pasteboard. Set window title and tab chrome background colorTo set the window title and tab color use this escape sequence:
Replace Example in bash that turns the background purple:
To reset the window title and tab color, use this code:
For example:
Change the color paletteTo change the current session's colors use this code:
If a color space is given, it should be one of: The following alternate schemes are also supported: * If A second escape sequence is also supported, but its use is not recommended:
Replace [rr] , [gg] , [bb] are 2-digit hex value (for
example, "ff"). Example in bash that changes the foreground color blue:
AnnotationsTo add an annotation use on of these sequences:
AddHiddenAnnotation does not reveal the annotation window at the time the escape sequence is received, while AddAnnotation opens it immediately. Cursor Guide
The Attention
The Background Image
The value of Report Cell Size
The terminal responds with either:
Or, in newer versions:
Report VariableEach iTerm2 session has internal variables (as described in Scripting Fundamentals). This escape sequence reports a variable's value:
Where
Where BadgeThe badge has custom escape sequences described here. DownloadsFor information on file downloads and inline images, see here. UploadsTo request the user select one or more files to upload, send:
In the future the When iTerm2 receives this it will respond with a status of If the user selects multiple files they will be placed in a directory within the tar file. Set Touch Bar Key LabelsYou can configure touch bar key labels for function keys and for the "status" button. The code used is:
Where
To pop them:
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:
Where Unicode VersioniTerm2 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:
Where You can push the current value on a stack and pop it off to return to the previous value by setting File TransferOSC 1337 ; File=[args] ST See Images for details. Custom Control SequencesiTerm2 allows scripts to define custom control sequences. See the Create Window example for a working demo. The control sequence is:
Where Shell Integration/FinalTermiTerm2's Shell Integration feature is made possible by proprietary escape sequences pioneered by the FinalTerm emulator. FinalTerm is defunct, but the escape sequences are documented here. ConceptsThe 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 Escape SequencesFinalTerm 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
Sent just before start of shell prompt. FTCS_COMMAND_START
Sent just after end of shell prompt, before the user-entered command. FTCS_COMMAND_EXECUTED
Sent just before start of command output. All text between FTCS_COMMAND_FINISHED
The interpretation of this command depends on which This command may be sent after If this command
is sent after If neither iTerm2 ExtensionsiTerm2 extends FinalTerm's suite of escape sequences. SetUserVar
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 for more information on variables and how they can be used.
ShellIntegrationVersionTwo forms are accepted. The second form is deprecated and should not be used:
Reports the current version of the shell integration script.
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
Reports the user name and hostname.
The following synonym is available as a combination of RemoteHost and CurrentDir:
where CurrentDir
Reports the current directory.
The following synonym is available as a combination of RemoteHost and CurrentDir:
where ClearCapturedOutput
Erases the current captured output. DECSCUSR 0
This will reset the cursor to its default appearance. This is an intentional deviation from the behavior of DEC virtual terminals. Curly Underlines
This turns on curly underlines. Extended Device AttributesReport terminal name and version.
iTerm2 will respond with:
Where [version] is the
version of iTerm2, such as |