A tiny macOS dialog for shell scripts and AI agents: ask the user a question, get the answer on stdout.
Think of it as a reverse toast. A toast is the system telling you something; gui-prompt is the system asking you something — a small floating window with a question, an editable text field, and buttons. Whatever the user types and clicks comes back as one line on stdout, so any script can branch on it.
That makes it a convenient way for an AI agent to ask its user for input or a decision. An agent working in a terminal, a background job, or a tool loop has no natural way to tap you on the shoulder; with gui-prompt it can put up one small window with the question, a prefilled answer to edit, and the choices as buttons — and get back a single line it can act on.
$ gui-prompt -q "Rename photo.jpg?" -d "2026-01-15_photo.jpg" -s "11:5" -a1 "Move to Today" -a2 "Move to Date"
ACTION1: 2026-01-15_photo.jpg
Requires macOS and the Xcode Command Line Tools (xcode-select --install).
git clone https://github.com/skywrite/gui-prompt.git
cd gui-prompt
./install.sh # compiles to ~/.local/bin/gui-prompt
./install.sh ~/.bin # or any other directory on your PATH
The source is also a runnable script — ./gui-prompt.swift -h works without installing, at the cost of ~0.3 s of startup per launch. The compiled binary starts instantly.
gui-prompt [OPTIONS] [question] [default]
-q, --question TEXT question shown above the field (also the window title)
-d, --default TEXT initial text in the field
-s, --select-range N:M preselect M characters starting at offset N
-a, --action TITLE extra button on the left; repeat for more, left to right
-a<N>, --action<N> TITLE the same, as button number N (-a1, -a2, -a3, ...)
-h, --help
Output is a single line on stdout:
OK: <text> OK clicked, or Enter
CANCEL: <text> Cancel clicked, Esc pressed, or window closed
ACTION<N>: <text> extra button N, counted from the left
<text> is always the field's current contents, whichever button was pressed. The exit status is 0 whenever the dialog ran; non-zero means it could not.
result=$(gui-prompt -q "Tag this file?" -d "untagged" -a "Skip")
status=${result%%: *}
answer=${result#*: }
case $status in
OK) echo "tagging as $answer" ;;
ACTION1) echo "skipped" ;;
*) echo "cancelled" ;;
esac- The window floats above other windows and appears without stealing focus; click it to type.
- Enter = OK, Esc = Cancel. Cmd+C/V/X/A work in the field.
- No Dock icon; the process exits as soon as the answer is printed.
- One question per process — call it again for the next one.
Extracted from Sky, where it drives the desktop file renamer (sky util:desktop:rename).
Apache-2.0