XPROMPT(1)

📦 version 2.5.0, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

okay so xprompt(1) is literally your read line utility for X, bestie — a whole prompt widget where you type stuff and it prints it back. It’s giving “input field but make it X11.”

✨ SYNOPSIS ✨

xprompt [-acdfips] [-G gravity] [-g geometry] [-h histfile] [-m monitor]
[-w windowid] [promptstr]

💅 DESCRIPTION 💅

xprompt is a prompt for X. It shows a text input field where you can type a text subject to tab-completion. When you press Return, the typed text is printed to the stdout. When you press Tab, a dropdown menu appears showing the items from stdin that match the word to be completed. It can read a list of newline-separated items from stdin. 💖

If the argument promptstr is given, the prompt string promptstr appears at the beginning of the input field. Cute.

xprompt resembles dmenu, but they differ in a subtle point: while dmenu completes the whole text, xprompt performs contextual completion. No cap, that’s the whole vibe. 🦋

The options are as follows:

  • -a — Enables argument mode. In this mode, xprompt looks for more arguments to complete after completing one argument. It’s giving “one word down, next word loading.” ✨
  • -c — Always show auto complete without having to press Tab. The dropdown just shows up like it owns the place. 💅
  • -d — Rather than complete item names, complete item descriptions. Item names are hidden and only descriptions are listed on the dropdown list. When clicking Enter, the hidden item name is printed to stdout. Sneaky but iconic.
  • -f — Enables filename completion. When the -f option is used, when no item from the standard input matches the current text, xprompt tries to complete a file name. Filesystem bestie behavior, fr fr.
  • -G gravity — Specify the gravity, that is, where in the screen or parent window to display xprompt. gravity can be "N" for NorthGravity (display on the top center of the screen); "SE" for SouthEastGravity (display on the bottom right corner of the screen); "C" for CenterGravity (display on the center of the screen); etc. Placement queen. 👑
  • -g geometry — Specifies the geometry in the form <WIDTH>x<HEIGHT>[{-+}<XOFFSET>{-+}<YOFFSET>]. Replace <WIDTH> by the desired width, <HEIGHT> by the desired height, and so on. A value of 0 sets a field to the default value. So, for example, -g 0x20+0+0 set the height to 20 pixels while maintaining other values to the default. <XOFFSET> and <YOFFSET> are optional and can be preceded by either a minus or a plus (meaning negative or positive values). So, for example, -g 0x20 is the same as -g0x20+0+0. Geometry math ate. 🎀
  • -h file — Specifies the file to be used for reading and storing the history of typed texts. Your typing lore goes here. 💜
  • -i — Makes xprompt match items case insensitively. HELLO and hello are literally the same vibe for matching purposes.
  • -m monitor — Makes xprompt be displayed on the monitor specified. Monitor numbers start from 0. Without this option, when xprompt is not embedded (i.e., without the -w option), xprompt is displayed on the same monitor of the focused window, or (if there is no focused window) on the monitor where the mouse is on. Monitor-aware king behavior. 🔥
  • -p — Enable password mode. In this mode, the typed text is not echoed in the input field. Secretive. 🙈
  • -s — Makes a single Enter or Esc keypress or mouse click on a item exit xprompt, regardless of a completion be in action. Without this option, when a completion is in action, a Enter or Esc keypress or a mouse click first exits the completion, and a second keypress exits xprompt. Two-step exit energy unless you turn this on. 💀
  • -w windowid — Renders xprompt embedded into the window windowid. It’s not a separate popup, it’s moving in. 🫶

Each item read from stdin has the following format:

ITEM := [TABS] WORD [TABS DESCRIPTION] NEWLINE

That means that each item is composed by zero or more tabs, followed by a text, followed by more tabs, followed by a description, followed by newline. Brackets group optional elements. Slay, grammar understood.

  • The initial tabs indicate the item hierarchy. An item without initial tabs is listed for completion at the beginning of the input field. An item with one tab is listed for completion for the second word in the input field. And so on. Hierarchy but make it tabs. ✨
  • The word is a string listed for completion in the dropdown list that appears when pressing Tab.
  • The second group of tabs separate the word from its description.
  • The description is a string describing what the word means.
  • The newline terminates the item specification.

xprompt saves the input text from previous runs in a history file specified by the -h option or by the XPROMPTHISTFILE environment variable. Memory but for prompts. 💖

🎀 USAGE 🎀

xprompt is controlled by the keyboard. Pressing Tab initiates the completion, pressing Up or Down navigates through the history. Keyboard girlie through and through.

xprompt supports XIM-based input methods with on-the-spot pre-editing. When the input method is in progress, the pre-edited text is underlined. It’s giving “I see what you’re composing.” 🦋

xprompt can also be controlled via Ctrl + Key keybindings with the XPROMPTCTRL environment variable. The default value for XPROMPTCTRL is "vcmpn::::aebf::ukhdwAEBF::zZ:". Each key or keybinding is assigned a operation like CTRLCANCEL, CTRLNEXT, CTRLRIGHT, etc. The default value for each operation is listed below between parentheses. No cap, the keymap is literally a little alphabet soup. 🍓

  • CTRLPASTE (Ctrl+V) — Paste from primary X selection.
  • CTRLCOPY (Ctrl+C) — Copy selected text into primary X selection.
  • CTRLENTER (Enter, Ctrl+M) — When completion is in operation, confirms text. When completion is not in operation, or when the -s option is supplied, prints the input text to stdout, and writes it to the history file, if the input text is different from the last entry in the history file.
  • CTRLPREV (Shift+Tab, Ctrl+P) — Selects the previous item in the completion dropdown list.
  • CTRLNEXT (Tab, Ctrl+N) — Selects the next item in the completion dropdown list.
  • CTRLPGUP (PgUp) — TODO.
  • CTRLPGDOWN (PgDown) — TODO.
  • CTRLUP (Up) — Select the previous entered text in the history.
  • CTRLDOWN (Down) — Select the next entered text in the history.
  • CTRLBOL (Home, Ctrl+A) — Move the cursor to the beginning of line.
  • CTRLEOL (End, Ctrl+E) — Move the cursor to the end of line.
  • CTRLLEFT (Left, Ctrl+B) — Move the cursor one character to the left.
  • CTRLRIGHT (Right, Ctrl+F) — Move the cursor one character to the right.
  • CTRLWLEFT (Ctrl+Left) — Move the cursor one word to the left.
  • CTRLWRIGHT (Ctrl+Right) — Move the cursor one word to the right.
  • CTRLDELBOL (Ctrl+U) — Delete from the cursor to the beginning of line.
  • CTRLDELEOL (Ctrl+K) — Delete from the cursor to the end of line.
  • CTRLDELLEFT (Backspace, Ctrl+H) — Delete one character to the left.
  • CTRLDELRIGHT (Delete, Ctrl+D) — Delete one character to the right.
  • CTRLDELWORD (Ctrl+W) — Delete one word to the left.
  • CTRLSELBOL (Shift+Home) — Select text from cursor to beginning of line.
  • CTRLSELEOL (Shift+End) — Select text from cursor to end of line.
  • CTRLSELLEFT (Shift+Left) — Select text from cursor to one character to the left.
  • CTRLSELRIGHT (Shift+Right) — Select text from cursor to one character to the right.
  • CTRLSELWLEFT (Ctrl+Shift+Left) — Select text from cursor to one word to the left.
  • CTRLSELWRIGHT (Ctrl+Shift+Right) — Select text from cursor to one word to the right.
  • CTRLUNDO (Ctrl+Z) — Undo the last editing operation.
  • CTLREDO (Ctrl+Shift+Z) — Redo an editing operation.
  • CTRLCANCEL (Esc) — When completion is in progress, exit completion without confirming text. When completion is not in progress, exit xprompt without printing anything.

xprompt can also be controlled with the mouse. Clicking on a item selects it. Clicking on the input field with the left button moves the cursor. Clicking on the input field with the middle button pastes from the primary selection. Clicking on the input field with the left button and moving the mouse selects text. Clicking on the input field with the left button twice selects a word. Clicking on the input field with the left button three times selects the whole text. Mouse behavior also ate, honestly. 🐭✨

🌈 ENVIRONMENT 🌈

The following environment variables affect the execution of xprompt.

  • XPROMPTHISTFILE — Specifies the file to be used for reading and storing the history of typed texts.
  • XPROMPTHISTSIZE — Specifies the number of entries to be kept in the history file.
  • XPROMPTCTRL — This environment variable is set to a list of alphabetic characters, each character specify a ctrl sequence for a input operation in the order listed in the section USAGE. For example, by default, XPROMPTCTRL is "vcmpn::::aebf::ukhdwAEBF::zZ:", it means that pressing Ctrl+V enters CTRLPASTE, Ctrl+C enters CTRLCOPY, Ctrl+M enters CTRLENTER, etc. A colon specifies that no Ctrl + Key sequence implements such operation. Colon = “nobody home” for that operation. 💀
  • WORDDELIMITERS — A string of characters that delimits words. By default it is a “ .,/:;\<>'[]{}()&$?!”. Delimiter lore, preserved exactly. 🎀

✨ RESOURCES ✨

okay so xprompt is very into X resources — it understands all of these, bestie 💅

  • xprompt.font — the font used to draw the text. You can stack multiple fonts as fallback fonts, and you separate them with a comma ✨
  • xprompt.background — the background color of the input text field, and of the non-selected items in the dropdown completion list 🎨
  • xprompt.foreground — the foreground color of the input text field, and of the non-selected items in the dropdown completion list
  • xprompt.description — the foreground color of the description of non-selected items in the dropdown completion list 🫶
  • xprompt.hoverbackground — the background color of the hovered items in the dropdown completion list
  • xprompt.hoverforeground — the background color of the hovered items in the dropdown completion list 🙈 (yes, "background", that's literally what the page says, no cap)
  • xprompt.hoverdescription — the foreground color of the description of hovered items in the dropdown completion list
  • xprompt.selbackground — the background color of the selected items in the dropdown completion list 👑
  • xprompt.selforeground — the background color of the selected items in the dropdown completion list (again: background, fr fr)
  • xprompt.seldescription — the foreground color of the description of selected items in the dropdown completion list
  • xprompt.border — the color of the border around xprompt 🎀
  • xprompt.separator — the color of the separator between the input field and the dropdown list
  • xprompt.borderWidth — the size in pixels of the border around xprompt
  • xprompt.separatorWidth — the size in pixels of the item separator
  • xprompt.items — how many items get listed in the dropdown completion list ⭐
  • xprompt.geometry — the geometry, in the form <WIDTH>x<HEIGHT>+<XOFFSET>+<YOFFSET>. Swap <WIDTH> for the width you want, <HEIGHT> for the height you want, and so on 💖. A value of 0 sets a field to its default value. So like, for example, 0x20+0+0 sets the height to 20 pixels while keeping the other values at their default — iconic, honestly.
  • xprompt.gravity — where on the screen (or parent window) xprompt gets displayed 🌈. It can be "N" for NorthGravity (top center of the screen); "SE" for SouthEastGravity (bottom right corner of the screen); "C" for CenterGravity (center of the screen); etc.

🌸 EXAMPLES 🌸

okay so picture this: a file with the following content, where \t means a tab character 👀

git
\t   add\t    Add file contents to the index.
\t   rm\t     Remove files from the working tree and from the index.
\t   mv\t     Move or rename a file, a directory, or a symlink.
\t   commit\t Record changes to the repository.
man
\t   cat
\t   cut
\t   ed
\t   vi
open

so when you pipe that file into xprompt as stdin, here's the whole vibe when you hit Tab 🦋

  • if the input field is empty, pressing Tab makes xprompt pop a dropdown list with these three entries: git, man, and open. It also shows descriptions after each completion ✨
  • if the input field has the word git at the beginning of the line, pressing Tab gives you a dropdown list with these four entries: add, rm, mv, and commit 💅
  • if the input field has the word man at the beginning of the line, pressing Tab gives you a dropdown list with these four entries: cat, cut, ed, and vi
  • if the input field has the word open at the beginning of the line, and xprompt was invoked with the -f option, then pressing Tab makes xprompt show a dropdown list of possible filenames — because no completion was specified at stdin 🎀

🦋 SEE ALSO 🦋

dmenu(1), xmenu(1) — go give the neighbors some love 💜

💀 BUGS 💀

okay so this is the tea: xprompt steals the input focus from the currently focused window (and does not give it back) 😭. This is necessary because xprompt needs the input focus for the X Input Method. Since xprompt is an override-redirect window, it doesn't get the focus by regular means from the window manager (because xprompt is not controlled by the window manager — instead xprompt controls itself and has to get the focus by its own means). And xprompt cannot be managed by the window manager because most window managers do not know how xprompt works or how it needs the entire focus for itself 🙈

so yeah — focus theft is a feature-not-a-bug situation here, but it is listed under BUGS, so, y'know. The more you know 🫶

and that's the whole page, bestie!! 🎀 that was XPROMPT(1) from start to finish — mwah, go forth and prompt ✨💖🌸

📦 where this page comes from