CSI CUP / HVP — Cursor Position

frame

CSI introducer: \x1b[ ESC [ (0x1B 0x5B)

terminator (none): ST · BEL

parameters / subcommands

gotchas

• Coordinates are 1-BASED (1;1 is top-left), not 0-based — off-by-one is the most common bug.
• Parameter order is ROW first then COLUMN (Pl ; Pc), the opposite of the (x,y) convention many programmers expect.
• With DEC origin mode (DECSET 6) enabled, CUP addresses relative to the top margin of the scroll region (DECSTBM), not the physical screen.
• Out-of-range coordinates are clamped to the screen/region bounds; they do not wrap or error.
• HVP ('f') and CUP ('H') are interchangeable in practice; emit 'H' for maximum portability.

provenance

• source: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html
• version: xterm ctlseqs, patch #410, 2026/04/19
• retrieved: 2026-05-29 · updated: 2026-05-29T00:00:00Z

per-fact attribution:

• #summary — https://invisible-island.net/xterm/ctlseqs/ctlseqs.html xterm ctlseqs: CSI Ps ; Ps H = Cursor Position [row;column] (CUP); CSI Ps ; Ps f = Horizontal and Vertical Position (HVP). Defaults are 1.
• ext.params — https://ecma-international.org/publications-and-standards/standards/ecma-48/ ECMA-48 defines CUP (final 'H') and HVP (final 'f'); parameters are line then column, both default 1, 1-based.

see also

• terminal-csi/cuu
• terminal-csi/cha
• terminal-csi/save-restore-cursor
• terminal-dec-private-mode/6