Triggers
WARNING: This document is for an older version of iTerm2.
A trigger is an action that is performed when text matching some regular expression is received in a terminal session.
How to Create a Trigger
To create a trigger, open the 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 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 Preferences > Number of screen lines to match against trigger regular expressions.
Actions
The following actions are available:
- Bounce Dock Icon: Makes the dock icon bounce until the iTerm2 window becomes key.
- Capture Output: Save the line to the Captured Output toolbelt tool. See Captured Output. The parameter is text to send (as though it had been typed) when you double-click on an entry in the Captured Output tool.
- Highlight Text: The text matching the regex in the trigger will change color. The parameter sets the color.
- Open Password Manager: Opens the password manager. You can specify which account to select by default.
- Post Notification: Posts a notification with Growl (if available) or Notification Center.
- 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.
- 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.
- 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, Send Growl Alert, Send Text, and Show Alert) require additional information. This is specified in the "Parameters" field. When the paramter is a text field with freeform entry, some special values are defined:
| Value | Meaning |
|---|---|
| \0 | The entire value matched by the regular expression. |
| \1, \2, ..., \9 | The nth value captured by the regular expression. |
| \a | A BEL character (^G). |
| \b | A backspace character ^H. |
| \e | An ESC character (ascii 27). |
| \n | A newline character. |
| \r | A linefeed character. |
| \t | A tab character. |
| \xNN | A hex value NN (for example: \x1b sends ascii code 27, an ESC). |
Instant
When Instant is set, the trigger will fire once per line as soon as the match occurs, without waiting for a newline. This was added for the benefit of the Open Password Manager trigger, since password prompts usually are not followed by a newline. This may cause certain regular expressions (for example, ".*") to match less than they otherwise might.
Example
The iTerm2-zmodem project demonstrates hooking up iTerm2 to zmodem upload and download.