OSC 1337 — iTerm2 proprietary control sequences

OSC 1337 is iTerm2's umbrella for proprietary features, taking a key=value (or key=value:base64payload) argument: OSC 1337 ; key=value ST. Notable sub-keys include SetUserVar, CurrentDir, RemoteHost, File (inline images, base64 in the payload after a ':'), and ShellIntegrationVersion. It is a single-vendor extension though several terminals have adopted parts of it.

aka: iTerm2 proprietary · OSC 1337 · ESC ] 1337 · inline images · imgcat · SetUserVar · CurrentDir

frame

OSC introducer: \x1b] ESC ] (0x1B 0x5D)

terminator (ST|BEL): ST \x1b\ · BEL \x07

parameters / subcommands

id	name	bytes (ST)	meaning
file	File — inline images / file transfer	\x1b]1337;File=inline=1:BASE64DATA\x1b\	OSC 1337 ; File=key=value;... : <base64 data> ST renders an image inline (or transfers a file). Args include inline=1, width, height, name (base64), size.
setuservar	SetUserVar — user variable	\x1b]1337;SetUserVar=git=YmFzZTY0\x1b\	OSC 1337 ; SetUserVar=name=<base64 value> ST sets a user-defined variable that iTerm2 status bars / badges can reference.
currentdir	CurrentDir — working directory	\x1b]1337;CurrentDir=/home/me\x1b\	OSC 1337 ; CurrentDir=/path ST tells iTerm2 the shell's current directory (used for new-tab-in-same-dir, etc.). OSC 7 is the cross-terminal equivalent.
remotehost	RemoteHost — user@host	\x1b]1337;RemoteHost=me@server\x1b\	OSC 1337 ; RemoteHost=user@host ST reports the logged-in remote host so iTerm2 can show it / detect ssh sessions.

gotchas

OSC 1337 is PROPRIETARY to iTerm2; do not assume other terminals implement it. WezTerm and a few others support the File (image) and SetUserVar subsets, but coverage is partial.
The File payload is base64-encoded image bytes after the ':'; values like name= are themselves base64. Get the inner encoding right or the image fails silently.
For portable inline images prefer the kitty graphics protocol or sixel where supported; for working-directory reporting prefer OSC 7 over CurrentDir.
Some keys (e.g. CurrentDir, RemoteHost) overlap with cross-terminal mechanisms (OSC 7, OSC 133); emit the portable one when you can.
Over ssh/tmux the sequence must be passed through (tmux requires the passthrough escape or it strips it).

provenance

source: https://iterm2.com/documentation-escape-codes.html
version: iTerm2 Proprietary Escape Codes documentation, retrieved 2026-05-29
retrieved: 2026-05-29 · updated: 2026-05-29T00:00:00Z

per-fact attribution:

#summary — https://iterm2.com/documentation-escape-codes.html iTerm2 documents OSC 1337 as its proprietary escape-code namespace: OSC 1337 ; key=value ST. Keys include SetUserVar, CurrentDir, RemoteHost, File (inline images), ShellIntegrationVersion, and others.

agent: curl -H 'accept: application/json' wire.phall.io/terminal-osc/1337 or /terminal-osc/1337.json

OSC 1337 — iTerm2 proprietary control sequences

frame

parameters / subcommands

gotchas

provenance

see also