Badges

A badge is a large text label that appears in the top right of a terminal session to provide dynamic status, such as the current host name or git branch. Its initial value is defined in Preferences>Profiles>General>Badge and it can be changed by an iTerm2-proprietary escape sequence. It may also reference iTerm2- and user-defined variables.

Here is an example of a session with a badge indicating the current user and host name.

Badge Format

The badge format is an interpolated string. See Scripting Fundamentals for more information on how to use interpolated strings to include information from the terminal state in the badge. It also describes how you can set user-defined variables, such as the current git branch, which may appear in the badge.

Here are some examples of interpolated strings:

\(session.username)@\(session.hostname)

User-defined badges can be very powerful. For example:

Current git branch on \(session.hostname) is \(user.gitBranch)

Undefined variables evaluate to an empty string.

Appearance

The badge's color may be set in Preferences>Profiles>Colors. Its position and typeface may be set in Preferences>Profiles>General. Note that the position is always relative to the top right of the session's viewport.

Escape Sequences

The badge may be set with the following escape sequence:

OSC 1337 ; SetBadgeFormat=Base-64 encoded badge format ST

Here's an example that works in bash:

# Set badge to show the current session name and git branch, if any is set.
printf "\e]1337;SetBadgeFormat=%s\a" \
  $(echo -n "\(session.name) \(user.gitBranch)" | base64)