Triggers

A trigger is an action that is performed when something happens in a terminal session. Most often the something is text matching a regular expression being received, but triggers can also fire in response to events such as a command finishing, the working directory changing, or a particular job starting.

How to Create a Trigger

To create a trigger, open the Settings panel. Select the Profiles tab. Choose the profile to which you wish to add a trigger. Then select the Advanced tab. Click the Edit button in the Triggers section. A panel opens that displays any existing triggers. You can click the + button to add a new trigger.

Every trigger has a match type, an action, and an optional parameter. The match type determines what causes the trigger to fire. When you add a trigger you choose its match type from a popup menu. There are two broad categories:

• Regular Expression: the trigger fires when received text matches a regular expression. This is the default and most common kind of trigger. Regex triggers may also be marked as Instant.
• Events: the trigger fires when a session event occurs, independent of any text on the screen. See Event Triggers below.

Regular Expression

Regular 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 Settings > Number of screen lines to match against trigger regular expressions. Null bytes in received text are treated as spaces for the purpose of trigger regex matching.

Actions

The following actions are available:

• Annotate: Associates a note with a matching text.
• Bounce Dock Icon: Makes the dock icon bounce until the iTerm2 window becomes key.
• Buffer Input: Starts or stops buffering typed input. See the Buffer Input feature.
• Capture Output: Save the line to the Captured Output toolbelt tool. See Captured Output. The parameter is a coprocess command to run when you double-click an entry in the Captured Output tool.
• Change Style: Modifies the style of matching text.
• Enter Workgroup: Turns the session into a Workgroup, a cluster of related sessions.
• Exit Workgroup: Leaves the current Workgroup. A leader-only option makes only the main session leaving tear the workgroup down.
• Fold to Named Mark: Collapses all lines between the matching line and a preceding named mark with a given name.
• Highlight Line: The entire line containing text matching the regex in the trigger will change color. The parameter sets the color.
• Highlight Text: The text matching the regex in the trigger will change color. The parameter sets the color.
• Inject Data: Inserts bytes into the input stream. These can be text or control sequences.
• Invoke Script Function: Executes a function call defined using the Python API.
• Make Hyperlink: The text matching the regex in the trigger will become a hyperlink which you can open with Cmd-Click. The parameter sets the URL.
• Open Password Manager: Opens the password manager. You can specify which account to select by default.
• Post Notification: Posts a notification with Notification Center.
• Prompt Detected: Informs iTerm2 that the shell prompt begins at the start of the match. Used to emulate Shell Integration features. If the prompt is one line long then use Instant.
• Report Directory: Tells iTerm2 what your current directory is. You can use this to enable Shell Integration features without installing the scripts. The parameter is your current directory.
• Report User & Host: Tells iTerm2 what your user or host name is. You can use this to enable Shell Integration features without installing the scripts. To specify just a user name, say `user@`. For just a host, say `@host`. For both, say `user@host`.
• Ring Bell: Plays the standard system bell sound once.
• Run Command: Runs a user-defined command.
• Run Coprocess: Runs a Coprocess.
• Run Silent Coprocess: Runs a Coprocess but do not show text that's being received (it only goes to the coprocess).
• Send Text: Sends user-defined text back to the terminal as though the user had typed it.
• Set Mark: Sets a mark. You can specify whether you'd like the display to stop scrolling after the trigger fires.
• Set Named Mark: Associates a name with the matching range. Various features help you navigate to named marks such as the Toolbelt tool and Open Quickly.
• Set Tab Status: Sets the session's status (dot indicator, subtitle, and subtitle color) shown on its tab. Part of the Session Status feature.
• Set Title: Sets the session's title.
• Set User Variable: Assigns a value to a user-defined [variable](https://iterm2.com/documentation-variables.html).
• Show Alert: Shows an alert box with user-defined text.
• Stop Processing Triggers: When this action is invoked no triggers further down the list will be invoked for the current text.

Parameter?

Various actions (Run Command, Run Coprocess, Post Notification, Send Text, and Show Alert) require additional information. This is specified in the "Parameters" field. When the parameter is a text field with freeform entry, some special values are defined:

For event triggers, \0 is not defined (there is no matched text), but \1, \2, and so on refer to values captured from the event as described in the Event Triggers table.

Instant

When Instant is set, the trigger will fire once per line as soon as the match occurs, without waiting for a newline. This was added for the benefit of the Open Password Manager trigger, since password prompts usually are not followed by a newline. This may cause certain regular expressions (for example, ".*") to match less than they otherwise might. Instant applies only to regular-expression triggers.

Job

Every trigger has an optional Job field. When it is set, the trigger is active only while a foreground job of that name is running (the match is case-insensitive). Leave it empty to keep the trigger active at all times. This makes it possible to write triggers that apply only while a particular program is running, for example Claude Code.

The Job field is distinct from the Job Started and Job Ended events: those events fire once when a job begins or ends, whereas the Job field gates whether a trigger is considered at all.

Event Triggers

Instead of matching a regular expression, a trigger can fire in response to a session event. Choose an event from the match-type popup when creating or editing a trigger. Any trigger action may be used with any event.

Most events have an optional filter so the trigger fires only for events you care about (for example, only when a command exits non-zero, or only when a process named claude starts). Leave a filter blank to match every occurrence. Each event also provides captured values that you can reference in the action's parameter as \1, \2, and so on.

The available events are:

Importing and Exporting Triggers

You can move triggers between profiles or share them with other people. In the trigger editor, select one or more triggers and click the share button. It offers Export to File, which writes an .it2triggers file, and Copy Trigger as URL to Clipboard, which puts a link to the selected triggers on the clipboard. Use the Import button to load triggers from an .it2triggers file.

Example

The iTerm2-zmodem project demonstrates hooking up iTerm2 to zmodem upload and download.