Please note that this is a "living document" and may lag or lead the state of the current stable release in a number of areas--as you might imagine, precisely documenting escape codes and their behaviors and cross-checking with the various technical documents is laborious and tedious and I only have so much spare time!

If you notice that something is inaccurate or missing, please do file an issue so that it can be resolved!

Output/Escape Sequences

WezTerm considers the output from the terminal to be a UTF-8 encoded stream of codepoints. No other encoding is supported. As described below, some C1 control codes have both 7-bit ASCII compatible as well as 8-bit representations. As ASCII is a compatible subset of UTF-8, the 7-bit representations are preferred and processed without any special consideration.

The 8-bit values are recognized, but only if the 8-bit value is treated as a unicode code point and encoded via a UTF-8 multi-byte sequence.

Printable Codepoints

Codepoints with value 0x20 and higher are considered to be printable and are applied to the terminal display using the following rules:

• Codepoints are buffered until a C0, C1 or other escape/control sequence is encountered, which triggers a flush and processing continues with the next step.
• The buffered codepoint sequence is split into unicode graphemes, which means that combining sequences and emoji are decoded. Processing continues for below for each individually recognized grapheme.
• If DEC line drawing mode is active, graphemes j-n, q, t-x are translated to equivalent line drawing graphemes and processing continues.
• If prior output/actions require it, the cursor position may be moved to a new line and the terminal display may be scrolled to make accomodate it.
• An appropriate number of cells, starting at the current cursor position, are allocated based on the column width of the current grapheme and are assigned to the grapheme. The current current graphics rendition state (such as colors and other presentation attributes) is also applied to those cells. If insert mode is active, those cells will be inserted at the current cursor position, otherwise they will overwrite cells at the current cursor position.
• The cursor position will be updated based on the column width of the grapheme.

After the graphemes are applied to the terminal display, the rendering portion of WezTerm will attempt to apply your font shaping configuration based on runs of graphemes with matching graphic attributes to determine which glyphs should be rendered from your fonts; it is at this stage that emoji and ligatures are resolved.

C0 Control Codes

Codepoints in the range 0x00-0x1F are considered to be C0 control codes. C0 controls will flush any buffered printable codepoints before triggering the action described below.

C1 Control Codes

As mentioned above, WezTerm only supports UTF-8 encoding. C1 control codes have an 8-bit representation as well as a multi-codepoint 7-bit escape sequence.

The 8-bit representation is recognized if the 8-bit value is treated as a unicode code point and encoded as a multi-byte UTF-8 sequence. Sending the 8-bit binary value will not be recognized as intended, as those bitsequences are passing through a UTF-8 decoder.

The table below lists the 7-bit C1 sequence (which is preferred) as well as the codepoint value, along with the corresponding meaning.

As with C0 control codes, C1 controls will flush any buffered printable codepoints before triggering the action described below.

Other Escape Sequences

As these sequences start with an ESC, which is a C0 control, these will flush any buffered printable codepoints before triggering the associated action.

CSI - Control Sequence Introducer Sequences

CSI sequences begin with the C1 CSI sequence, which is either the 7-bit ESC [ sequence or the codepoint 0x9B.

WezTerm classifies these sequences into a number of functional families which are broken out below.

Graphic Rendition (SGR)

SGR sequences are of the form CSI DIGITS [; DIGITS ]+ m. That is, any number of semicolon separated numbers, terminated by the m codepoint. There are a handful of slightly more modern sequences that use colon : codepoints to encode additional context.

The digits map to one of the codes in the table below, which manipulate the presentation attributes of subsequently printed characters.

It is valid to omit the code number; for example CSI m is equivalent to CSI 0 m which resets the presentation attributes.

There are a handful of additional SGR codes that allow setting extended colors; unlike the codes above, which are activated by a single numeric parameter out of SGR sequence, these the extended color codes require multiple parameters. The canonical representation of these sequences is to have the multiple parameters be separated by colons (:), but for compatibility reasons WezTerm also accepts an ambiguous semicolon (;) separated variation. The colon form is unambiguous and should be preferred; the semicolon form should not be used by new applications and is not documented here in the interest of avoiding accidental new implementations.

CSI 38:5 - foreground color palette index

This sequence will set the foreground color to the specified palette INDEX, which can be a decimal number in the range 0-255.

CSI 38 : 5 : INDEX m

CSI 48:5 - background color palette index

This sequence will set the background color to the specified palette INDEX, which can be a decimal number in the range 0-255.

CSI 48 : 5 : INDEX m

CSI 58:5 - underline color palette index

This sequence will set the underline color to the specified palette INDEX, which can be a decimal number in the range 0-255.

CSI 58 : 5 : INDEX m

CSI 38:2 - foreground color: RGB

This sequence will set the foreground color to an arbitrary color in RGB colorspace. The R, G and B symbols below are decimal numbers in the range 0-255. Note that after the 2 parameter two colons are present; its really an omitted colorspace ID parameter but that nature of that parameter is not specified in the accompanying ITU T.416 specification and is ignored by WezTerm and most (all?) other terminal emulators:

CSI 38 : 2 : : R : G : B m

(Since 20210814-124438-54e29167) For the sake of compatibility with some other terminal emulators this additional form is also supported where the colorspace ID argument is not specified:

CSI 38 : 2 : R : G : B m

CSI 38:6 - foreground color: RGBA

{{since('20220807-113146-c2fee766')}}

This is a wezterm extension: wezterm considers color mode 6 as RGBA, allowing you to specify the alpha channel in addition to the RGB channels.

CSI 38 : 6 : : R : G : B : A m

CSI 48:2 - background color: RGB

This sequence will set the background color to an arbitrary color in RGB colorspace. The R, G and B symbols below are decimal numbers in the range 0-255:

CSI 48 : 2 : : R : G : B m

(Since 20210814-124438-54e29167) For the sake of compatibility with some other terminal emulators this additional form is also supported where the colorspace ID argument is not specified:

CSI 48 : 2 : R : G : B m

CSI 48:6 - background color: RGBA

{{since('20220807-113146-c2fee766')}}

This is a wezterm extension: wezterm considers color mode 6 as RGBA, allowing you to specify the alpha channel in addition to the RGB channels.

CSI 48 : 6 : : R : G : B : A m

CSI 58:2 - underline color: RGB

This sequence will set the underline color to an arbitrary color in RGB colorspace. The R, G and B symbols below are decimal numbers in the range 0-255:

CSI 58 : 2 : : R : G : B m

(Since 20210814-124438-54e29167) For the sake of compatibility with some other terminal emulators this additional form is also supported where the colorspace ID argument is not specified:

CSI 58 : 2 : R : G : B m

CSI 58:6 - underline color: RGBA

{{since('20220807-113146-c2fee766')}}

This is a wezterm extension: wezterm considers color mode 6 as RGBA, allowing you to specify the alpha channel in addition to the RGB channels.

CSI 58 : 6 : : R : G : B : A m

Cursor Movement

Editing Functions

Mode Functions

{{since('20210814-124438-54e29167')}}

WezTerm supports Synchronized Rendering. DECSET 2026 is set to batch (hold) rendering until DECSET 2026 is reset to flush the queued screen data.

Device Functions

Window Functions

DCS - Device Control String

The C1 DCS escape places the terminal parser into a device control mode until the C1 ST is encountered.

In the table below, DCS can be either the 7-bit representation (ESC P) or the 8-bit codepoint (0x90).

Operating System Command Sequences

Operating System Command (OSC) sequences are introduced via ESC ] followed by a numeric code and typically have parameters delimited by ;. OSC sequences are canonically delimited by the ST (String Terminator) sequence, but WezTerm also accepts delimiting them with the BEL control.

The table below is keyed by the OSC code.

Additional Resources

• xterm's escape sequences
• iTerm2's escape sequences
• kitty's escape sequences
• Terminology's escape sequences
• This Google spreadsheet aims to document all the known escape sequences.
• Wikipedia's ANSI escape code page