Proprietary Escape Codes
WARNING: This document is for an older version of iTerm2.
iTerm2 supports several non-standard escape codes. These may not work properly in tmux or screen, and may have unknown effects on other terminal emulators. Proceed with caution.
A quick comment on notation: in this document, ^[ means "Escape" (hex code 0x1b) and ^G means "bel" (hex code 0x07).
The OSC command
50 used to be used but it conflicts with xterm, so it is now
Set cursor shape
where N=0, 1, or 2.
- 0: Block
- 1: Vertical bar
- 2: Underline
Add this to your .vimrc to change cursor shape in insert mode:
let &t_SI = "\<Esc>]1337;CursorShape=1\x7" let &t_EI = "\<Esc>]1337;CursorShape=0\x7"
This is derived from Konsole.
The "Set Mark" (cmd-shift-M) command allows you to record a location and then jump back to it later (with cmd-shift-J). The following escape code has the same effect as that command:
To bring iTerm2 to the foreground:
Clear Scrollback History
To erase the scrollback history:
Set curent directory
To inform iTerm2 of the current directory to help semantic history:
Post a Growl notification
To post a Growl notification:
^9;Message content goes here^G
This will have no effect if Growl is not running.
To change the session's profile on the fly:
Copy to clipboard
To place text in the pasteboard:
Where name is one of "rule", "find", "font", or empty to mean the general pasteboard (which is what you normally want). After this is sent, all text received is placed in the pasteboard until this code comes in:
Set window title and tab chrome background color
To set the window title and tab color use this escape sequence:
^6;1;bg;red;brightness;N^G ^6;1;bg;green;brightness;N^G ^6;1;bg;blue;brightness;N^G
Replace N with a decimal value in 0 to 255.
Example in bash that turns the background purple:
echo -e "\033]6;1;bg;red;brightness;255\a" echo -e "\033]6;1;bg;green;brightness;0\a" echo -e "\033]6;1;bg;blue;brightness;255\a"
To reset the window title and tab color, use this code:
echo -e "\033]6;1;bg;*;default\a"
Change the color palette
Replace "n" with:
- 0-f (hex) = ansi color
- g = foreground
- h = background
- i = bold color
- j = selection color
- k = selected text color
- l = cursor
- m = cursor text
rr, gg, bb are 2-digit hex value (for example, "ff"). Example in bash that changes the foreground color blue:
echo -e "\033]Pg4040ff\033\\"
To add an annotation use on of these sequences:
^1337;AddAnnotation=message^G ^1337;AddAnnotation=length|message^G ^1337;AddAnnotation=message|length|x-coord|y-coord^G ^1337;AddHiddenAnnotation=message^G ^1337;AddHiddenAnnotation=length|message^G ^1337;AddHiddenAnnotation=message|length|x-coord|y-coord^G
- message: The message to attach to the annotation.
- length: The number of cells to annotate. Defaults to the rest of the line beginning at the start of the annotation.
- x-coord and y-coord: The starting coordinate for the annotation. Defaults to the cursor's coordinate.
AddHiddenAnnotation does not reveal the annotation window at the time the escape sequence is received, while AddAnnotation opens it immediately.
The boolean should be yes or no. This shows or hides the cursor guide.
The boolean should be yes to request attention by bouncing the dock icon and no to cancel a previous request.
The value of base64 is a base64-encoded filename to display as a background image. If it is an empty string then the background image iwll be removed. User confirmation is required as a security measure.
Report Cell Size
The terminal responds with:
Where height and width are floating point values giving the size in points of a single character cell. For example:
The badge has custom escape sequences described here.
For information on file downloads and inline images, see here.
iTerm2's Shell Integration feature is made possible by proprietary escape sequences pioneered by the FinalTerm emulator. FinalTerm is defunct, but the escape sequences are documented here.
OSCstands for Operating System Command. In practice it refers to this sequence of two ASCII characters: 27, 93 (
STstands for String Terminator. It terminates an OSC sequence and consists either of two ASCII characters 27, 92 (
esc \) or ASCII 7 (
OSC sequences always begin with
OSC, are followed by a sequence of
characters, and are terminated with
OSC codes begin with a number (one or more decimal digits), which we'll
call the "command" in this document. If the command takes parameters it will be
followed by a semicolon and the structure of the rest of the body of the
sequence is dependent on the command. Well-behaved terminal emulators ignore
OSC codes with unrecognized commands.
The goal of the FinalTerm escape sequences is to mark up a shell's output with semantic information about where the prompt begins, where the user-entered command begins, and where the command's output begins and ends.
[PROMPT]prompt% [COMMAND_START] ls -l
-rw-r--r-- 1 user group 127 May 1 2016 filename
FinalTerm originally defined various escape sequences in its original spec that are not supported by iTerm2 and are not described in this document. The best remaining references to these codes are in iTerm2's source code.
OSC 1 3 3 ; A ST
Sent just before start of shell prompt.
OSC 1 3 3 ; B ST
Sent just after end of shell prompt, before the user-entered command.
OSC 1 3 3 ; C ST
Sent just before start of command output. All text between
FTCS_COMMAND_EXECUTED at the time
FTCS_COMMAND_EXECUTED is received
excluding terminal whitespace is considered the command the user entered. It is
expected that user-entered commands will be edited interactively, so the screen
contents are captured without regard to how they came to contain their state.
If the cursor's location is before (above, or if on the same line, left of) its
FTCS_COMMAND_START was received, then the command will be
treated as the empty string.
OSC 1 3 3 ; D ; Ps ST
OSC 1 3 3 ; D ST (for cancellation only)
The interpretation of this command depends on which
FTCS was most recently
received prior to
This command may be sent after
FTCS_COMMAND_START to indicate that a command
was aborted. All state associated with the preceding prompt and the command
until its receipt will be deleted. Either form is accepted for an abort. If the
Ps argument is provided to an abort it will be ignored.
If this command is sent after
FTCS_COMMAND_EXECUTED, then it indicates the
end of command prompt. Ps is the command's exit status, a number in the range
0-255 represented as one or more ASCII decimal digits. A status of 0 is
considered "success" and nonzero indicates "failure." The terminal may choose
to indicate this visually.
FTCS_COMMAND_EXECUTED was sent prior to
FTCS_COMMAND_FINISHED it should be ignored.
iTerm2 extends FinalTerm's suite of escape sequences.
OSC 1 3 3 7 ; S e t U s e r V a r = Ps1 = Ps2 ST
Sets the value of a user-defined variable. iTerm2 keeps a dictionary of key-value pairs which may be used within iTerm2 as string substitutions, such as in the Badge.
Ps1 is the key.
Ps2 is the base64-encoded value.
OSC 1 3 3 7 ; S h e l l I n t e g r a t i o n V e r s i o n = Pn ; Ps ST
OSC 1 3 3 7 ; S h e l l I n t e g r a t i o n V e r s i o n = Pn ST (deprecated)
Reports the current version of the shell integration script.
Pn is the version.
Ps is the name of the shell (e.g.,
iTerm2 has a baked-in notion of the "current" version and if it sees a lower number the user will be prompted to upgrade. The version number is specific to the shell.
OSC 1 3 3 7 ; R e m o t e H o s t = Ps1 @ Ps2 ST
Reports the user name and hostname.
Ps1 is username. Ps2 is fully-qualified hostname.
OSC 1 3 3 7 ; C u r r e n t D i r = Ps1 ST
Reports the current directory.
Ps1 is the current directory.