Table of Contents

Triggers

A trigger is an action that is performed when text matching some regular expression is received in a terminal session.

What can Triggers Do?

Various actions may be assigned to triggers. These include:

  • Bounce Dock Icon: Makes the dock icon bounce until the iTerm2 window becomes key.
  • Ring Bell: Plays the standard system bell sound once.
  • Run Command: Runs a user-defined command.
  • Run Coprocess: Runs a Coprocess.
  • Send Growl Alert: If Growl is enabled, a Growl alert is sent.
  • Send Text: Sends user-defined text back to the terminal as though the user had typed it.
  • Show Alert: Shows an alert box with user-defined text.

What is a 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. Some special values are allowed here:

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).

Example

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

Technical Details

Regular expressions conform to the ICU regular expressions rules. Text that is written to the screen and bells are sent to the regex matcher for evaluation. Only one line at a time is matched. Matching is performed when a newline or cursor-moving escape code is processed. Lines longer than 1024 characters are truncated at the 1024th character for performance reasons.

New features in 2.9 and later

Open Password Manager

This trigger opens the password manager. Its parameter is the name of an account in the password manager to select by default.

Instant Triggers

Since their inception, triggers would only fire at the end of a line (or in a few other cases, such as when part of the line is erased). The nightly build now has an "Instant" property for each trigger. 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.