Keyword highlighting¶

korTTY can color words and patterns in terminal output as it arrives — errors in red, warnings underlined, IP and MAC addresses, interface names and link states on network devices — so the lines that matter stand out while output scrolls by. Highlighting only changes how the text looks: what the server sent, what you copy, the terminal log and what the AI features read stay exactly the same.

Highlighting is off until you switch it on, for one pane with a menu or the shortcut, for every terminal of a connection with the connection's rule set, or for every pane with a default rule set. Each terminal pane shows at most one rule set at a time. korTTY ships three built-in sets, and you can create your own.

A rule of your own can also notify you: when its pattern appears in new output in a tab you are not looking at, such as No space left on device during a long backup, korTTY marks the tab and shows a desktop notification. See Notifications for matching output.

A rule can instead run one of your snippets in the pane where its pattern appears, for example a script that collects diagnostics when BUILD FAILED shows up. korTTY asks you before the first run in each connection and keeps such a rule from running in a loop. See Running a snippet when output matches.

Built-in rule sets¶

The built-in sets use the theme's ANSI colors, so they follow your color settings and the colors of each connection. Every rule also makes its text bold or underlined, so a match still stands out for color-blind users and in a monochrome theme.

Switching highlighting on and off¶

Highlighting works per pane: in a split tab every pane can show a different set, and a new split takes over a set chosen for the pane it was split from; without such a choice it follows its own connection.

• Keyboard: Ctrl+Shift+H (Cmd+Shift+H on macOS) switches highlighting on or off for the pane that has the keyboard focus. Switching it back on brings back the set that pane showed last; a pane that never showed one starts with its connection's rule set or the default rule set, or with Errors and warnings when there is neither. The status bar names the set that is now on.
• View → Highlighting: Highlighting On does the same as the shortcut. Below it, pick None or a rule set for the focused pane of the active tab.
• Terminal context menu: right-click a pane and open Highlighting for the same entries, applied to the pane you clicked. The submenu is there even when terminal effects are switched off.

Both menus list your own rule sets below the built-in ones and end with Manage Rule Sets…, which opens the rule-set editor on the set the pane shows.

The shortcut also works while the menu bar is hidden and in terminal-only fullscreen. On Windows and Linux korTTY keeps Ctrl+Shift+H for itself, so it does not reach the program in the terminal; plain Ctrl+H still reaches the shell as backspace.

Default rule set and settings¶

The Keyword highlighting section of Configuration → Global Settings → Terminal holds four settings that apply to every pane; see Terminal settings for the details.

A pane shows the first of these that applies:

1. the set chosen for that pane in a menu or with the shortcut, including None;
2. the connection's rule set, including None;
3. the default rule set;
4. no highlighting.

A rule set that no longer exists is skipped, so the next level decides. Saving the settings moves every open pane to the set it now resolves to, so a new default appears at once in every pane whose connection and pane have no choice of their own.

Rule set per connection¶

A connection can have a rule set of its own, for example Network devices for your switches and routers and Errors and warnings for application servers. Open the connection in the Connection Manager, switch to the Terminal Settings tab and pick the set under Keyword highlighting in the Terminal behavior section:

• The section applies whether or not the connection uses its own terminal settings, and it stays when terminal effects are switched off. While the master switch in Settings → Terminal is off, the section says so and no set shows.
• Saving in the Connection Manager moves the open panes of that connection, in every window, to the new set at once. A pane with a set chosen in a menu or with the shortcut keeps that choice until you change it there.
• Tabs opened from the saved connection through Quick Connect, Duplicate or a project use its set. A pane opened with Split Right (new connection) or Split Down (new connection) follows the connection it was opened to, unless it took over a set chosen for the pane it was split from.
• The choice is stored with the connection in connections.xml and survives duplicating, exporting and importing; an export carries only the id of the set, never its rules. A set that no longer exists — because you deleted it, or because the connection was exported on another computer or comes from a shared teamwork file — is shown as Missing rule set in the dropdown, and the connection's panes follow the default rule set until you pick another one. The built-in sets have the same id on every computer.

Your own rule sets¶

The rule-set editor creates and changes your own rule sets. Open it with View → Highlighting → Manage Rule Sets…, with Manage Rule Sets… in a pane's Highlighting context submenu, or with Edit Rules… next to the default rule set in Configuration → Global Settings → Terminal.

• Rule sets on the left lists the built-in sets, marked built-in, and then yours. The built-in sets are read-only, but you can select one to read its patterns. Duplicate copies the selected set, built-in or your own, into a new set you can change; New starts an empty set with one rule to fill in, and Delete removes one of your sets.
• Rule set name is the name the menus and the default rule set dropdown show.
• Rules lists the set's rules in priority order: where two rules match the same text, the upper rule wins, as in the built-in sets. Use ▲ and ▼ to change the order, Add Rule to add a rule below the selected one and Remove Rule to delete it. On switches a rule off without deleting it. Pattern shows each pattern in the look it gives, Applies to whether it colors the matched text or the whole line, Action shows Notify or Run snippet for a rule with an action, Hits how many places it highlights in the test text below (for a rule that only acts, the lines it would act on), and Check whether something is wrong with it.
• Below the table you edit the selected rule. Pattern is a word or phrase to find, or a Java regular expression when Regular expression is on. Ignore case matches upper and lower case alike, and Whole word only matches where the hit is not part of a longer word, so error marks ERROR: but not terror. Applies to colors either the Matched text or the Whole line, soft-wrapped rows included.
• Text color and Background are Unchanged (the program's own color), one of the 16 theme colors, or Custom with a color picker. Theme colors follow your color settings and the colors of each connection, like the built-in sets; a custom color stays the same everywhere. Style adds Bold, Italic or Underline. A rule needs at least one color, style or action.
• Action is Highlight only, Desktop notification for a rule that notifies when its pattern appears in new output, or Run a snippet for a rule that runs the snippet you pick under Snippet. A rule with an action may leave the text as it is: without a color or style it changes nothing on screen, and the rules below it still color what it matches. Include the matched text adds what the pattern matched to the notification. Snippet lists the snippets of the Snippet Manager, with their folder in parentheses; a rule whose snippet was deleted shows Missing snippet. Rule name is what the notification, the confirmation and the tab's tooltip call the rule; a rule without a name is called by its pattern.

The Test text at the bottom starts with sample log and network-device lines; replace it with output of your own. Preview shows it the way a terminal pane would, using the same matching, the same rule order and the same time limit, and it follows every change as you type. Only the first 100 lines of the test text are previewed, and the editor says so when the text is longer. The editor keeps your test text until korTTY quits; it is not saved.

Check says Invalid for a rule that cannot work, Off for a rule you switched off, Slow for a rule that needed more than half of its time limit on a line of the test text, and Too slow for a rule that ran out of time there and highlights nothing on that line; a terminal pane switches such a rule off once it has run out of time on three lines (see Limits). Hover over the word, or select the rule, for the explanation. While any rule or set has a problem, OK is disabled and the line above the buttons names the first one, for example a missing pattern, a regular expression that does not compile, or a pattern such as a* that also matches empty text. A pattern, a rule name or a set name must not contain an invisible character that the settings file cannot store, such as U+FFFF or half of a surrogate pair; the message below the rule, or below the set's name, names the character as U+FFFF so you can find and remove it.

OK saves your rule sets to global-settings.xml at once and moves every open pane to its updated set; Cancel discards all changes. Deleting the set that is your default rule set sets the default back to None. A pane that showed a deleted set falls back to the next level: its connection's rule set, else the default rule set.

Notifications for matching output¶

A rule whose Action is Desktop notification watches for you: when its pattern appears in new output in a tab you are not looking at, korTTY marks the tab with 🔔 and shows a desktop notification, by the same rules as the other terminal notifications. Use it for the lines you wait for while you work elsewhere, such as No space left on device, BUILD FAILED or a link going down on a switch console. Like every rule it only works while its rule set is shown in the pane: choose the set for the pane, for the connection or as the default rule set.

• The notification is titled korTTY · and the name of the tab, so a program can never make it look like a message from another application. Its text is the rule's Rule name, or its pattern when it has none, and never terminal output. Pointing at the marked tab shows A highlight rule matched new output in this tab: and the name.
• Clicking the notification brings korTTY's window to the front, selects the tab and focuses the pane the rule matched in; see Clicking a notification.
• With Include the matched text on, the notification also shows what the pattern matched, for example Disk full: No space left on device. korTTY removes control characters, line breaks and the invisible characters that change the reading direction, and cuts it to 100 characters. Leave it off for patterns that can match passwords, tokens or customer data: a notification can appear on the lock screen.
• Each rule notifies at most once every 30 seconds per pane; a match in that time only keeps the mark on the tab. Two rules count on their own. Nothing happens in the tab you are looking at, and the mark goes away as soon as you look at the tab.
• Only new output counts. A line notifies when the pattern first appears on it, and again only when the match on it changes or the line is cleared and written anew, so a progress line that keeps rewriting ERROR count: 3 notifies once.
• Output that was already in the pane never notifies: the saved screen of a project, which korTTY shows again when you open the project, what the pane shows when it gets a rule set or when you edit a rule, the lines a window resize rebuilds, and korTTY's own messages in the pane, such as connection notices. Full-screen programs such as vim, less, htop and tmux never notify, even when you allow highlighting in them.
• Output that arrives within 2 seconds of keys you typed in another pane reaching the pane through broadcast mode or multi-exec, typically their echo, never notifies. The panes that take part in multi-exec share one notification per rule, so an error that every server prints notifies once.
• A notifying rule never types anything into the terminal, and no rule ever types text from the output or answers a prompt. The server decides what it prints, so an action that sends keys would let it type commands for you. The only thing a rule can type is a snippet you picked yourself (see the next section). To answer prompts automatically, script it with the control API.
• Run actions of highlight rules (notifications, snippets) in Settings → Terminal switches every rule with an action off at once; the rules then only highlight, and the rule editor says so below the action. In a managed installation the policy key terminal-triggers decides and locks that setting (see Enterprise policy); while it forbids them, the editor keeps you from giving a rule an action.

Running a snippet when output matches¶

A rule whose Action is Run a snippet types the snippet you picked under Snippet into the pane where its pattern appears in new output, as Send to Terminal in the Snippet Manager does: korTTY fills in the stored values of its variables and, for bash, shell, Python, Perl and Ruby, announces the snippet by name and sends it as one line. Use it for follow-ups you would otherwise type yourself, such as collecting diagnostics after BUILD FAILED or showing the disk usage after No space left on device. Like every rule it only works while its rule set is shown in the pane, whether you are looking at the tab or not.

• The first time a rule wants to run its snippet in a connection, korTTY asks: the question names the rule, the snippet and the connection and shows the start of the snippet. Allow for this connection runs it now and from then on in every pane of that connection; Don't allow, or closing the question, keeps it from running there. Don't allow is the default button, so Enter or a space you meant for the terminal when the question appeared refuses rather than allows. Your answer applies to that rule and snippet until you quit korTTY; a rule that is changed to run another snippet asks again. While the question is open, further matches are ignored.
• A rule runs its snippet at most once every 30 seconds per pane, and no rule runs a snippet within 5 seconds of the last run in that pane, so the snippet's own output cannot set off the next run at once.
• If rules run snippets three times in a row in a pane, each within 2 minutes of the one before — typically a snippet whose output matches its own rule, or two rules that keep setting each other off — korTTY stops running snippets in that pane and says so in the pane. They run again once 2 minutes pass without a match there.
• The snippet goes to the matching pane only: broadcast mode and multi-exec never pass it on. Output that answers keys mirrored into the pane by them never runs a snippet, and neither does a match while a korTTY terminal agent or a coding agent works in the pane, which would take the snippet as its own input, while a full-screen program such as vim or less has the pane, which would take it as keystrokes, or while a paste is still being sent into the pane line by line. The same is checked again when you allow a snippet, since the pane may have changed while the question was open.
• The line the cursor is on never runs a snippet: that is the command you are typing at the prompt, or a program's question waiting for your answer. A rule never answers prompts.
• As for notifications, only new output counts: never a project's restored screen, what the pane shows when it gets a rule set or when you edit a rule, korTTY's own messages in the pane, or full-screen programs.
• A snippet cannot ask for values when a rule runs it. If it uses a declared variable without a stored value, it does not run and the pane says which variable needs one; store it in the Variable Manager (Variables... in the Snippet Manager). The pane also says when the snippet no longer exists. A snippet that is empty or cannot be put on one command line does not run either, and the pane says so. Each of these is said once per rule and pane.
• When a rule ran its snippet in a tab you are not looking at, the tab gets the 🔔 mark and its tooltip names the snippet.
• The snippet is typed as if you typed it at that moment: if a program is still running in the pane, that program reads it, or the shell runs it once the program ends, and it follows anything you have typed at the prompt but not yet sent with Enter.

How highlighting behaves¶

• New output is highlighted a moment after it appears (about 50 ms), on a background thread, so a fast cat or a log tail keeps its speed.
• A match can continue across a soft-wrapped line, and patterns match wide characters such as CJK text and emoji.
• Choosing another set, or None, re-colors the screen at once and the scrollback progressively, newest lines first. None restores the original colors everywhere.
• Full-screen programs such as vim, less and htop are not highlighted unless you allow it in the settings: they redraw constantly and bring their own colors, so highlights would flicker and fight them.
• When output floods in faster than it can be checked, lines more than 10,000 rows above the bottom are left as they are.
• Text a program marks as concealed stays hidden, and links keep their own style.
• Highlights also show on connections whose terminal colors are switched off, and they appear in terminal recordings, because they are part of what the pane shows.
• While the find bar shows results, korTTY waits with re-coloring the scrollback after you switch sets, so the matches you are looking at stay marked. A line that is highlighted while the find bar is open can lose its find mark; search again to bring it back.

Limits¶

Each rule gets at most 2 ms per line of output. A rule that runs out of time three times — usually a regular expression that backtracks badly — is switched off for that pane until you choose a set again. A line, soft-wrapped rows included, is checked up to its first 8,192 characters. The editor's Check column warns about slow rules before they reach a terminal.

You can create up to 32 rule sets with up to 64 rules each, and a pattern can be up to 512 characters long.

Security and privacy¶

A rule that notifies turns output into notifications, so a server can trigger one by printing the pattern, just as a program can ring the bell. That is why the notification names only your rule and its tab unless you ask for the matched text, and why it comes at most every 30 seconds per rule and pane.

A rule that runs a snippet lets a server's output start a script you chose, so a server can make it run by printing the pattern. That is why it asks you once per connection, runs only snippets from your own Snippet Manager and never text from the output, leaves the line you type alone, waits at least 30 seconds between runs and stops after three runs in a row. Give such rules patterns that only appear when you want the snippet to run, and snippets that are safe to run more than once.

Rule sets stay on your computer, in global-settings.xml (see Configuration files), and the log names rules and sets by their ids only, never by their patterns or by the text they matched. If you allowed anonymous usage statistics, korTTY reports which built-in set was switched on (any set of your own counts only as "custom") and whether that happened from a menu, with the shortcut, through the connection's rule set or through the default rule set, and which of the four settings you changed, with the default rule set again reported only as a built-in set, "custom" or "none" — never patterns, set names or terminal text.