wire / terminal-osc /
4
OSC 4 — Set / query color palette entry
OSC 4 ; c ; spec ST sets palette color number c to spec, where spec is an X11 color name or rgb:RR/GG/BB form. OSC 4 ; c ; ? ST queries the current value of palette entry c; the terminal replies with OSC 4 ; c ; rgb:RRRR/GGGG/BBBB ST. Lets a program recolor or read any of the 256 indexed colors at runtime.
terminal-osc kind control-sequence status de-facto verification verified tier B terminal-escape@1
aka: set color palette · query color palette · OSC 4 · ESC ] 4 · set ANSI color
frame
OSC introducer: \x1b] ESC ] (0x1B 0x5D)
terminator (ST|BEL): ST \x1b\ · BEL \x07
parameters / subcommands
| id | name | bytes (ST) | meaning |
|---|
| set | Set color | \x1b]4;1;rgb:ff/00/00\x1b\ | OSC 4 ; c ; spec ST sets palette index c (0–255) to spec. spec is an X11 color name (e.g. 'red') or an rgb:RR/GG/BB / #RRGGBB form. Multiple c ; spec pairs may be concatenated in one sequence. |
| query | Query color | \x1b]4;1;?\x1b\ | OSC 4 ; c ; ? ST asks the terminal for the current value of palette index c. The terminal replies with OSC 4 ; c ; rgb:RRRR/GGGG/BBBB ST (note 16-bit-per-channel form in the reply). |
gotchas
- The query REPLY uses 16-bit-per-channel rgb:RRRR/GGGG/BBBB (four hex digits per channel), while many setters use 8-bit rgb:RR/GG/BB; do not assume the reply width matches what you wrote.
- Reading a query reply requires the program to read from the tty and parse the OSC; if the terminal does not support the query (or it is disabled), the read blocks — always use a timeout.
- Use OSC 104 to reset palette entries back to their defaults (OSC 104 with no parameters resets all colors).
- Related OSCs set special colors, not palette indices: OSC 10 = default foreground, OSC 11 = default background, OSC 12 = cursor color. These are distinct from OSC 4's indexed palette.
- spec parsing follows X11 XParseColor: names, #RGB / #RRGGBB / #RRRGGGBBB / #RRRRGGGGBBBB, and rgb:/rgbi: forms are accepted; portability is best with the rgb:RR/GG/BB form.
provenance
per-fact attribution:
- #summary — https://invisible-island.net/xterm/ctlseqs/ctlseqs.html xterm ctlseqs: Ps = 4 ; c ; spec -> Change Color Number c to the color specified by spec. Any number of c ; spec pairs may be given. A '?' for spec queries and the terminal reports the color back with a control sequence of the same form.
agent: curl -H 'accept: application/json' wire.phall.io/terminal-osc/4
or /terminal-osc/4.json