XTERMCONTROL(1)

✨ XTERMCONTROL ✨

okay bestie, gather round, because this is the manual page for xtermcontrol — a User Commands girlie that lives in your terminal and does dynamic control of XFree86 xterm properties. yes she's giving main character energy. yes she can change your colors mid-session. no cap. 🎀

---

💖 NAME 💖

xtermcontrol — dynamic control of XFree86 xterm properties.

---

🌸 SYNOPSIS 🌸

xtermcontrol [OPTIONS]...

---

🦋 DESCRIPTION 🦋

so like, xtermcontrol makes it easy to change colors, title, font and geometry of a running xterm(1), and it can also report the current settings of all those same properties. the way that it just… does both?? obsessed. 💅

window manipulations are supported too, and they are: de-/iconify, raise/lower, maximize/restore, and reset. full glow-up menu, fr fr. ✨

and to complete the feature set — because she's an overachiever and we love her for it — xtermcontrol lets advanced users issue any xterm control sequence of their choosing. raw. unfiltered. iconic. 🔥

---

👑 OPTIONS 👑

• --fg=COLOR — set the foreground color (see also COLOR NAMES).
• --bg=COLOR — set the background color.
• --colorN=COLOR — set the N'th color, where N is [0-255], to COLOR. like, e.g. --color88=COLOR. 💖
• --highlight=COLOR — set the highlight color.
• --cursor=COLOR — set the cursor color.
• --mouse-fg=COLOR — set the mouse pointer foreground color.
• --mouse-bg=COLOR — set the mouse pointer background color.
• --font=FONT — set the font name (see also FONT NAMES). alternatively you can specify a fontmenu index as #[0-6], or navigate the fontmenu by relative sizes as #+Nor#-N`, where N is an optional integer. yes, optional. she's flexible like that. 🧚
• --title=STRING — set the window title. heads up though: mechanisms like the bash(1) PROMPT_COMMAND may just come along and overwrite your title. rude of them, honestly. 😭
• --geometry=WIDTHxHEIGHT+XOFF+YOFF — set size and/or position. so here's the tea: through its control sequences, the xterm only recognizes positive XOFF and YOFF offsets, which are pixels relative to the upper left hand corner of the display. that means xtermcontrol is unable to handle negative offsets as described in the X(7x) GEOMETRY SPECIFICATIONS, so it truncates negative values to zero. periodt. 💀
• --get-fg — report the foreground color.
• --get-bg — report the background color.
• --get-colorN — report the N'th color, where N is [0-255], e.g. --get-color88.
• --get-highlight — report the highlight color.
• --get-cursor — report the cursor color.
• --get-mouse-fg — report the mouse pointer foreground color.
• --get-mouse-bg — report the mouse pointer background color.
• --get-font — report the font.
• --get-title — report the window title.
• --get-geometry — report size and position. the size of the text area is reported in characters, and the position is reported in pixels relative to the upper left hand corner of the display. iykyk. 👑
• --maximize — maximize the window.
• --restore — restore the maximized window.
• --iconify — iconify the window.
• --de-iconify — de-iconify the window.
• --raise — raise the window.
• --lower — lower the window.
• --reset — full reset.
• --raw=CTLSEQS — issue a raw control sequence (see also XTERM CONTROL SEQUENCES).
• --file=FILE — source a configuration FILE (see also CONFIGURATION).
• --force, -f — skip the TERM environment variable check.
• --verbose, -v — print verbose reports.
• --help, -h — print the help message and exit.
• --version — print the version number and exit.

---

🎀 CONFIGURATION 🎀

the default configuration file ~/.xtermcontrol is sourced if xtermcontrol is run without options, or if you specifically request it, e.g. 'xtermcontrol --file=~/.xtermcontrol'. 💖

each line in a configuration file is either a comment or contains an attribute. attributes consist of a keyword and an associated value:

keyword = value # comment

the valid keyword/value combos are, and yes we're listing all of them, every single one, no skipping bestie:

foreground="COLOR"
background="COLOR"
highlight="COLOR"
cursor="COLOR"
mouse-foreground="COLOR"
mouse-background="COLOR"
geometry="WIDTHxHEIGHT+XOFF+YOFF"
font="FONT"
color0="COLOR"
color1="COLOR"
color2="COLOR"
color3="COLOR"
color4="COLOR"
color5="COLOR"
color6="COLOR"
color7="COLOR"
color8="COLOR"
color9="COLOR"
color10="COLOR"
color11="COLOR"
color12="COLOR"
color13="COLOR"
color14="COLOR"
color15="COLOR"

whitespace is ignored in attributes unless it's within a quoted value. the character # is taken to begin a comment — each # and all remaining characters on that line get ignored. so don't be out here starting comments when you meant to write a color. 🙈

---

🌈 FONT NAMES 🌈

xtermcontrol accepts any X(7x) FONT NAMES. font names like -adobe-courier-medium-r-normal--10-100-75-75-m-60-iso8859-1 are, and i quote, very cumbersome to write, so it's convenient to make use of aliases — e.g. fixed or 8x13 — if they're present in fonts.alias files of the font directories. save your wrists, bestie. 💅

---

⭐ COLOR NAMES ⭐

xtermcontrol accepts any X(7x) COLOR NAMES. basically that means colors are specified by name or rgb value, e.g. blue, rgb:0000/0000/FFFF or #00F. colors are typically reported by the xterm in a device-dependent numerical form, e.g. rgb:0000/0000/FFFF.

okay important: old syntax rgb values should always be quoted to avoid # being interpreted as the beginning of a comment by the shell (see also FILES). do not skip the quotes, i'm begging. 😭

---

💀 XTERM CONTROL SEQUENCES 💀

the secret behind xtermcontrol is xterm control sequences. all the possible ones — and there are a plethora of them, like genuinely so many — are documented in ctlseqs.txt, found in the xterm(1) distribution (see also FILES). go read it. it's giving forbidden knowledge. 📖✨

---

🍓 MACOS TERMINAL.APP 🍓

the macOS Terminal.app emulates an extended set of the VTxxx series commands, closely resembling dtterm. so because of that, the following subset of xtermcontrol options works as expected:

--title
--geometry
--get-geometry
--maximize
--restore
--iconify
--de-iconify
--raise
--lower
--reset

color names are ignored, but device-dependent numerical form and rgb values work as expected for the following subset of xtermcontrol options (see also COLOR NAMES):

--fg
--get-fg
--bg
--get-bg
--cursor
--get-cursor
--mouse-fg
--get-mouse-fg
--mouse-bg
--get-mouse-bg

---

🫶 TROUBLESHOOTING 🫶

if read/write permissions on the tty's are changed so that special group membership is required to be able to write to the pseudo terminal, the easiest workaround is to install xtermcontrol setuid root. (yes, that's the workaround. yes, it's a little spicy. no, i don't make the rules.)

Xterm(1) has three resources — allowWindowOps, allowTitleOps, and allowFontOps — that enable or disable special operations which xtermcontrol relies on. if any of these resources are set (or default) to 'false', xtermcontrol may hang. 😭 the resources correspond to xtermcontrol options like this:

allowWindowOps:
   --raise
   --lower
   --restore
   --maximize
   --iconify
   --de-iconify
   --get-title
   --geometry
   --get-geometry

allowTitleOps:
   --title

allowFontOps:
   --font
   --get-font

all three resources can usually be enabled for the current xterm session via a menu — ctrl+rightclick and look for menu item names like 'Allow Window Ops'. 🖱️✨

to set these resource values persistently, you can add the following to either your local ~/.Xdefaults file, or to a system-wide resource file like /etc/X11/app-defaults/XTerm:

*VT100.allowWindowOps: true
*VT100.allowTitleOps: true
*VT100.allowFontOps: true

---

🧚 FILES 🧚

• <XRoot>/X11/rgb.txt — default rgb color name file location.
• ctlseqs.txt — xterm control sequences documentation. distributed with xterm from http://dickey.his.com/xterm/

---

💜 SEE ALSO 💜

xterm(1), X(7x)

---

🌸 COPYRIGHT 🌸

Copyright © 2002-2022 Jess Thrysoee <jess@thrysoee.dk>

---

okay that's the whole page, you ate it, you read it, you're basically an xterm whisperer now. 💅✨

and for the cute sign-off: this is xtermcontrol 3.8, dated May 27, 2022, straight from the XTERMCONTROL(1) manual. slay, go change some colors bestie 🎀💖🦋