Table of Contents

Badges

WARNING: This document is for an older version of iTerm2.

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.

Availability

Support for badges is available in version 2.9 and later, currently distributed in the nightly builds and is in the master branch of the GitHub repo. It is not in version 2.1.1.

Variables

A badge may reference variables. There are two kinds of variables: user-defined variables and iTerm2-defined variables. User-defined variables may be set by an escape sequence described below.

The syntax for referencing a variable is to place the variable name between \( and ). For example:

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

Undefined variables evaluate to an empty string.

iTerm2-Defined Variables

The following variables are defined by iTerm2:

Variable Name Description
session.name The current session's name. Defaults to the profile name. May be changed with the escape sequence OSC 1 ; name ST, or by editing the session title in View>Edit Current Session.
session.columns The number of columns in the current session.
session.rows The number of rows in the current session.
session.hostname The current hostname. Only set if Shell Integration is installed.
session.username The current username. Only set if Shell Integration is installed.
session.path The current path. Works best if Shell Integration is installed.

User-Defined Variables

You can provide additional information in the form of user-defined variables. To create a user-defined variable you must modify your shell's rc script by defining a function named iterm2_print_user_vars that calls iterm2_set_user_var one or more times. See the example below.

Here's an example that sets a user-defined variable called "gitBranch" to the git branch of the current directory. Pick your shell to see the version you need: bash | fish | tcsh | zsh

# bash: Place this in .bashrc.
function iterm2_print_user_vars() {
  iterm2_set_user_var gitBranch $((git branch 2> /dev/null) | grep \* | cut -c3-)
}


To reference a user-defined variable, refer to it as \(user.variableName). For example, to use the example above, you could set your profile's badge to:

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

Escape Sequences

User-defined variables may be set with the following escape sequence:

OSC 1337 ; SetUserVar=name=Base64-encoded value ST

This is what iterm2_set_user_var sends. Generally you should use the iterm2_print_user_vars mechanism described above instead of sending this escape sequence directly.

The badge itself 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)

Color

The badge's color may be set in Preferences>Profiles>Colors.