Alert

Alert settings are named settings objects stored at $HOME/.config/qtermy/alerts. Alerts can be created and edited from the Manage Alerts window. The files can also be edited directly in a text editor, but note that qtermy does not monitor for external changes to settings files. Use the reload files button in the Manage Alerts window to load external changes and new files without restarting the application.

An alert is a description of a terminal condition, together with the action that should be taken when the condition becomes true. An alert can be made active in a terminal from the Terminal menu, various context menus, or by using the SetAlert action. Only one alert can be active in a terminal at any given time.

When the condition described by the action becomes true in the terminal, the action will trigger and the action described by the alert will be taken. The alert will then be made inactive and will not trigger again in that terminal. An alert can also be made inactive from the Terminal menu, various context menus, or by using the ClearAlert action.

Alerts can be favorited in the Manage Alerts window, which will cause them to appear at the top of alert selection menus.

Settings Categories

Condition

Type (enumeration)

The type of condition that the alert will monitor for. The choices are as follows:

  • Activity in terminal: Any activity is reported by the terminal. This includes printable output as well as non-printing output such as control characters, bells, or region updates.
  • Inactivity in terminal: No activity occurs in the terminal for the duration of time specified by InactivityTime.
  • Command finishes in terminal: A job finishes in the terminal with any exit status. This requires shell integration.
  • Command succeeds in terminal: A job finishes in the terminal with an exit status of zero. This requires shell integration.
  • Command fails in terminal: A job finishes in the terminal with a nonzero exit status. This requires shell integration.
  • String seen in terminal: The literal string specified by SearchString is printed to the terminal. This must occur after the alert is made active (scrollback is not searched).
  • Regex seen in terminal: Any string matching the ECMAScript regular expression specified by by SearchString is printed to the terminal. This must occur after the alert is made active (scrollback is not searched).
  • Bell seen in terminal: A bell character (BEL, Ctrl+G) is printed to the terminal.
  • Attribute is string: The terminal attribute named by AttributeName becomes equal to the literal string specified by SearchString. If this condition is true when the alert is set, the alert will trigger immediately.
  • Attribute is regex: The terminal attribute named by AttributeName matches the ECMAScript regular expression specified by SearchString. If this condition is true when the alert is set, the alert will trigger immediately.
InactivityTime (integer)

The time that the terminal must remain idle before the alert triggers, if the condition Type is set to monitor for inactivity.

SearchString (string)

The search string or regular expression to match. Several condition types make use of this setting. See Type.

AttributeName (string)

The terminal attribute name to monitor, if the condition Type is set to monitor for changes to an attribute.

Actions

SwitchProfile (boolean)

If enabled, the terminal will be switched to the configured Profile when the alert is triggered.

PushProfile (boolean)

If enabled, the terminal will be pushed to the configured Profile when the alert is triggered.

InvokeAction (boolean)

If enabled, the configured Action will be invoked when the alert is triggered.

RunLauncher (boolean)

If enabled, the configured Launcher will be launched with no marker substitutions when the alert is triggered.

DesktopNotify (boolean)

If enabled, the name of the alert and the configured Message will be passed to NotifySend to show a desktop notification when the alert is triggered.

ShowIndicator (boolean)

If enabled, an "urgent" indicator icon will be displayed on the terminal thumbnail in the Terminals tool when the alert is triggered.

The "urgent" indicator icon will be cleared when input focus moves to or from the affected terminal, or when ClearAlert is called on the terminal.

FlashThumbnail (boolean)

If enabled, the the terminal thumbnail in the Terminals tool will flash the number of times configured by Flashes when the alert is triggered.

MoveTerminalForward (boolean)

If enabled, ReorderTerminalFirst will be called on the terminal when the alert is triggered.

MoveServerForward (boolean)

If enabled, ReorderServerFirst will be called on the terminal's server when the alert is triggered.

Parameters

Profile (string)

The profile to use if SwitchProfile or PushProfile is enabled.

Action (string)

The action to invoke if InvokeAction is enabled. The strings <terminalId> and <serverId> within the action string will be replaced as appropriate at invocation time. Any other action parameters must be hard-coded.

Launcher (string)

The launcher to run if RunLauncher is enabled.

Flashes (integer)

The number of times to flash the terminal thumbnail if FlashThumbnail is enabled.

Note

Thumbnail flashing may be interrupted if the terminal thumbnail is flashed for another reason, such as a ThumbnailBell or ExitStatusEffect.

Message (string)

The message to use as the Body parameter to NotifySend if DesktopNotify is enabled. The name of the alert itself is used as the Summary parameter.