YAD(1)

📦
version 15.0 · 6 versions
, in arch rolling, nixpkgs unstable

okay bestie, welcome to YAD(1) — the User Commands page for yad, and it's literally giving iconic shell-script-dialog energy. grab a lil snack, we're going through every option together 💅

✨ NAME ✨

yad — display GTK+ dialogs from shell scripts or command-line. yes, that's the whole vibe: GTK+ dialogs, but make it scriptable 🫶

🌸 SYNOPSIS 🌸

yad [OPTIONS]

💖 DESCRIPTION 💖

YAD is a program that displays GTK+ dialogs and returns the user's input — either in the return code or on standard output. so you can present information to the user and ask for information back from, like, all manner of shell scripts. main character energy fr fr ✨

YAD is the fork of the Zenity program. no cap.

👑 OPTIONS 👑

bestie, this program follows the usual GNU command line syntax, with long options starting with two dashes. okay so let's go 👇

🎀 Dialog options 🎀

  • --about — display the about dialog.
  • --app — display the application selection dialog.
  • --calendar — display the calendar dialog.
  • --color — display the color selection dialog.
  • --dnd — display a drag-and-drop box.
  • --entry — display the text entry dialog.
  • --icons — display a box with shortcut icons.
  • --file — display the file selection dialog.
  • --font — display the font selection dialog.
  • --form — display the form dialog.
  • --html — display the HTML dialog.
  • --list — display the list dialog.
  • --notebook — display the notebook dialog.
  • --notification — display the notification icon.
  • --appindicator — display the appindicator icon.
  • --popup — display a popup message dialog.
  • --print — display the print dialog.
  • --progress — display the progress indication dialog.
  • --scale — display the scale dialog.
  • --text-info — display the text information dialog.

✨ General options ✨

  • --title=TITLE — set the dialog title.
  • --window-icon=ICON — set the window icon.
  • --width=WIDTH — set the dialog window width.
  • --height=HEIGHT — set the dialog window height.
  • --posx=NUMBER — set the X position of the dialog window. NUMBER can be negative.
  • --posy=NUMBER — set the Y position of the dialog window. NUMBER can be negative.
  • --geometry=WIDTHxHEIGHT+X+Y — use standard X Window geometry notation for placing the dialog. when this option is used, the width, height, posx, posy, mouse and center options are ignored. periodt.
  • --timeout=TIMEOUT — set the dialog timeout in seconds.
  • --timeout-indicator=POSITION — show the timeout indicator in the given position. positions are top, bottom, left or right. style of the indicator may be set through the user's CSS styles.
  • --kill-parent=[SIGNAL] — send SIGNAL to the parent process. default value of SIGNAL is a SIGTERM. SIGNAL may be specified by its number or symbolic name with or without the SIG prefix. see signal(7) for details about signals.
  • --print-xid=[FILENAME] — output the X Window ID of a yad's window to the specified file or to stderr.
  • --plug=KEY — run the dialog in plug mode for swallow as a notebook tab. see the NOTEBOOK section for more.
  • --tabnum=NUMBER — set the tab number for the plugged dialog. see the NOTEBOOK section for more.
  • --text=STRING — set the dialog text.
  • --text-width=NUMBER — set the maximum dialog text width in characters.
  • --text-align=TYPE — set the type of dialog text justification. TYPE may be left, right, center or fill.
  • --image=IMAGE — set the dialog image which appears on the left side of the dialog's text. IMAGE might be a file name or an icon name from the current icon theme.
  • --icon-theme=THEME — use the specified GTK icon theme instead of the default.
  • --keep-icon-size — don't scale icons. this option affects icons outside the icon theme.
  • --expander=[TEXT] — hide the main widget with an expander. TEXT is an optional argument with the expander's label.
  • --button=BUTTON:ID — add a dialog button. may be used multiple times. ID is an exit code or a command. BUTTON may be a yad stock item name for predefined buttons (like yad-close or yad-ok) or text in the form LABEL[!ICON[!TOOLTIP]] where ! is an item separator. full list of stock items may be found in the STOCK ITEMS section. if no buttons are specified, OK and Cancel buttons are used. see the EXIT STATUS section for more. if ID has a non-numeric value it's treated as a command, and clicking on such a button doesn't close the dialog.
  • --no-buttons — don't show buttons.
  • --buttons-layout=TYPE — set the buttons layout type. possible types are spread, edge, start, end or center. default is end.
  • --no-markup — don't use pango markup in the dialog's text.
  • --no-escape — don't close the dialog if Escape was pressed.
  • --escape-ok — Escape acts like pressing the OK button.
  • --always-print-result — print the result for any of the return codes. this option doesn't work if timeout was reached or Escape was pressed.
  • --use-interp=[INTERP] — all commands run under the specified interpreter. default is bash -c "%s". this option can reduce quoting in commands. if %s is specified, it will be replaced by the command. otherwise the command will be appended to the end of the command line.
  • --uri-handler=CMD — use CMD as the uri handler. by default yad uses the open-command parameter from settings. the URI replaces %s in the command string or is added as the last part of the command line.
  • --f1-action=CMD — set the command running when F1 was pressed.
  • --workdir=PATH — set the current working directory to PATH.
  • --borders=NUM — set the dialog window borders.
  • --sticky — make the window visible on all desktops.
  • --fixed — make the window fixed width and height.
  • --center — place the window in the center of the screen.
  • --mouse — place the window under the mouse position.
  • --on-top — place the window over other windows.
  • --undecorated — make the window undecorated (remove title and window borders).
  • --skip-taskbar — don't show the window in the taskbar and pager.
  • --maximized — run the dialog window maximized.
  • --fullscreen — run the dialog in fullscreen mode. this option may not work on all window managers.
  • --window-type=TYPE — create a window with the specified window type. TYPE can be one of normal, dialog, utility, dock, desktop, tooltip, notification or splash. the behavior of each window type depends on your window manager. see the EWMH specification for details.
NOTE: Tiling window managers will often float a "dialog" window but tile a "normal" window.
  • --no-focus — the dialog window never takes focus.
  • --close-on-unfocus — close the dialog window when it loses focus.
  • --selectable-labels — if set, the user can select the dialog's text and copy it to the clipboard. this option also affects label fields in the form dialog.
  • --image-path=PATH — add the specified path to the standard list of directories for looking for icons. this option can be used multiple times.
  • --rest=FILENAME — read extra arguments from the given file instead of the command line. each line of the file is treated as a single argument.
  • --response=NUMBER — set the default exit code to NUMBER instead of 0.
  • --css=STRING — read and parse additional GTK+ CSS styles from the given data. if STRING is a filename, the content of the file is loaded. if not, STRING is treated like CSS data.
  • --gtkrc=FILENAME (Deprecated) — read and parse additional GTK+ CSS styles from the given file. this option is deprecated. use --css instead.
  • --hscroll-policy=TYPE — set the policy type for horizontal scrollbars. TYPE can be one of auto, always or never. default is auto.
  • --vscroll-policy=TYPE — set the policy type for vertical scrollbars. TYPE can be one of auto, always or never. default is auto.
  • --enable-spell — enable spell checking in textview widgets.
  • --spell-lang=LANGUAGE — set spell checking language to LANGUAGE. by default the language is guessed from the current locale. use yad-tools(1) to get a list of all possible languages.
  • --bool-fmt=TYPE — set the output type of boolean values to TYPE. possible types are T, t, Y, y, O, o and 1. T and t are for the true/false pair in the appropriate case. Y and y are for the yes/no pair in the appropriate case. O and o are for the on/off pair in the appropriate case. 1 is for the 1/0 pair.
  • --write-settings — write yad settings to a file. see the SETTINGS section.

💅 Custom about dialog options 💅

  • --pname=STRING — set the program name.
  • --image=IMAGE — set the program icon name.
  • --pversion=STRING — set the program version string.
  • --copyright=STRING — set the program copyright string.
  • --comments=STRING — set the program detailed description.
  • --license=STRING — set the program license. the value of this option can be one of the predefined licenses (GPL2, GPL3, LGPL2, LGPL3, BSD, MIT or ARTISTIC), a file name with license text, or an arbitrary string.
  • --authors=STRING — set the list of program authors separated by comma.
  • --website=URI — set a link to the program website.
  • --website-label=LABEL — set a label for the program website link.

🦋 Application selection options 🦋

  • --enable-fallback — show fallback applications.
  • --enable-other — show other applications.
  • --enable-all — show all available applications.
  • --extened — shown extended information about the chosen application. by default only the executable is shown. in extended form the output fields are name, display name, description, icon and executable.

additional argument for the application dialog is a mime-type. if the mime-type is not specified, text/plain will be used.

🍓 Calendar options 🍓

  • --day=NUMBER — set the calendar day.
  • --month=NUMBER — set the calendar month.
  • --year=NUMBER — set the calendar year.
  • --date-format=PATTERN — set the format for the returned date. by default it's %x. see strftime(3) for more details.
  • --show-weeks — show the week numbers at the left side of the calendar.
  • --details=FILENAME — read days description from FILENAME.

the file with days details must be in the following format:

<date> <description>

the date field is a date in the format specified with the --date-format option. description is a string with date details, which may include Pango markup.

  • --select-action=COMMAND — run the specified command on selecting a date. the selected date is added at the end of a command in the form YEAR MONTH DAY.

🎨 Color selection options 🎨

  • --init-color=COLOR — sets the starting color value, so the dialog opens already showing the color you picked. 💖
  • --gtk-palette — shows the system palette inside the color dialog. Heads up: on GTK+3 builds this option shows the palette instead of the color editor, okay? different vibe, still cute.
  • --picker — adds a screen color picker button, so you can just go grab a color off your screen. obsessed. ✨
  • --alpha — adds opacity to the output color string. transparency slay.
  • --palette=[FILENAME] — shows a palette and sets predefined colors from the filename you give it. If you don't give one, yad uses /etc/X11/rgb.txt by default. no cap.
  • --expand-palette — the expander for the list of user-defined colors will be initially opened. so it starts unfolded, ready to go 🫶
  • --mode=MODE — sets the output color mode. Possible values are hex or rgb, and the default is hex. HEX mode looks like #rrggbbaa, and RGB mode looks like rgba(r, g, b, a). In RGBA mode opacity has values from 0.0 to 1.0 — literally decimals, not 0–255. 💅

🖱️ Drag-and-Drop box options 🖱️

  • --tooltip — uses the dialog text as a tooltip for the Drag-and-Drop box. hover and learn, bestie.
  • --command=CMD — runs the command when data is received. Data strings pass to the command as an argument, or they replace the %s modifier in the command. By default the data just prints to stdout. simple as that.
  • --exit-on-drop=NUMBER — exits after NUMBER drops were reached. And 0 means an infinite number of drops — that's the default, so it just keeps going forever unless you say otherwise. 🔥

⌨️ Text entry options ⌨️

  • --entry-label=STRING — sets the entry label text.
  • --entry-text=STRING — sets the initial entry text, or the default item in a combo-box.
  • --hide-text — hides the entry text. secret entry energy 🙈
  • --completion — uses completion instead of a combo-box.
  • --complete=TYPE — uses a specific type for extended completion. TYPE can be:
    • any — match any of the typed words
    • all — match all of the typed words
    • regex — when the typed text is treated as a regular expression
  • --editable — allows making changes to the text in a combo-box. edit away 💅
  • --numeric — uses a spin button instead of a text entry. Additional parameters on the command line are treated as minimum and maximum values, step value and precision (in that order). All these values are optional. The default range is from 0 to 65535 with step 1. ⭐
  • --float-precision=NUMBER — sets the precision of floating point numbers. By default precision is three digits after the point.
  • --licon=IMAGE — sets an icon on the left side of the entry. 🎀
  • --licon-action=CMD — specifies a command which will be run when the left icon is clicked. The output of that command will be set as the entry text. iconic behavior tbh.
  • --ricon=IMAGE — sets an icon on the right side of the entry. matching set, we love it.
  • --ricon-action=CMD — specifies a command which will be run when the right icon is clicked. The output of the command will be set as the entry text.
  • --num-output — outputs the index of the active element instead of the text, for a combo-box entry. numbers > words, iykyk.

Any extra data specified on the command line gets added as items of the combo-box entry — except in numeric mode, where that's not a thing.

If an icon is specified and no icon action is given, clicking the icon just clears the entry. And numeric fields will ignore the icons entirely. rip icons, you tried. 💀

🖼️ Iconbox options 🖼️

  • --read-dir=PATH — reads .desktop files from the specified directory.
  • --monitor — watches for changes in the directory and automatically updates the content of the iconbox. live updates, we stay refreshed ✨
  • --generic — uses the field GenericName instead of Name for the shortcut label.
  • --sort-by-name — uses the field Name instead of the filename for sorting items.
  • --descend — sorts items in descending order. Note that if data is read from stdin, this option is useless without --sort-by-name. fr fr, don't skip it.
  • --listen — reads data from stdin. The data must be in order: Name, Tooltip, Icon, Command, InTerm, separated by newline. InTerm is a case insensitive boolean constant (TRUE or FALSE). Sending a FormFeed character clears the iconbox. 🌀
  • --item-width — sets items width.
  • --icon-size — forces using the specified icon size. This option doesn't work in compact mode, just so you know. 😭
  • --compact — uses compact mode. Icon and name of each item is placed in a single row. tiny and tidy.
  • --single-click — activates items by a single mouse click. Heads up: this option may not work properly in the case of compact mode. 💀
  • --term — pattern for terminal. By default it uses xterm -e %s where %s is replaced by the command.

If both a directory and stdin are specified, the content of the iconbox will be read from the directory. directory wins, no debate. 👑

📁 File selection options 📁

  • --filename=FILENAME — sets the filename.
  • --multiple — allows selection of multiple filenames in the file selection dialog. more is more 💖
  • --directory — activates directory-only selection.
  • --save — activates save mode.
  • --separator=STRING — specifies the separator character when returning multiple filenames.
  • --confirm-overwrite=[TEXT] — confirms file selection if the filename already exists. The optional argument is a text for the confirmation dialog. protective queen behavior 🫶
  • --quoted-output — output values will be shell-style quoted.

🔤 Font selection options 🔤

  • --fontname=FONTNAME — sets the initial font. FONTNAME is a string with a font representation in the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]". yes, all those brackets are part of the deal.
  • --preview — sets the preview text. so you can see the font before committing, cute.
  • --separate-output — separates output of the selected font description.
  • --separator=STRING — sets the output separator character. Default is |. 🌸
  • --quoted-output — output data will be in shell-style quotes.

📝 Form options 📝

  • --field=LABEL[!TOOLTIP][:TYPE] — adds a field to the form. TYPE may be H, RO, NUM, CHK, CB, CBE, CE, FL, SFL, DIR, CDIR, FN, MFL, MDIR, DT, SCL, SW, APP, ICON, CLR, BTN, FBTN, LINK, LBL or TXT. Let's break them down, bestie:
    • H — hidden field type. All characters are displayed as the invisible char.
    • RO — the field is in read-only mode.
    • NUM — the field is a numeric. The initial value format for this field is VALUE[!RANGE[!STEP![PREC]]], where RANGE must be in the form MIN..MAX. ! is a default item separator. PREC is a precision for decimals.
    • CHK — checkbox field. Initial value is a case insensitive boolean constant (TRUE or FALSE).
    • CB — combo-box field. Initial value is a list VAL1!VAL2!.... The separator is the same as in the NUM field. A value started with ^ is treated as the default for the combo-box.
    • CBE — editable combo-box field. Initial value same as for combo-box.
    • CE — entry with completion. Initial value same as for combo-box.
    • FL — file selection button.
    • SFL — field for creating a file.
    • DIR — directory selection button.
    • CDIR — field for creating a folder.
    • FN — font selection button. Initial value same as in the font dialog.
    • MFL — select multiple files. The value of this field is a list of files separated by the item separator.
    • MDIR — select multiple folders. The value of this field is a list of folders separated by the item separator.
    • DT — date field.
    • SCL — scale field. The value of this field is in a range 0..100.
    • SW — switch field. Initial value is a case insensitive boolean constant (TRUE or FALSE).
    • APP — application selection button. The input value for this field is a mime-type. The output value is an executable for the selected application.
    • ICON — icon field. Like an average entry field but it has two icons. Left shows the current icon and right is clickable and calls yad-con-browser for choosing an icon.
    • CLR — color selection button. Output values for this field are generated in the same manner as for the color dialog.
    • BTN — button field. The label may be in the form LABEL[!ICON[!TOOLTIP]] where ! is an item separator. LABEL is the text of the button label or a yad stock id. ICON is the button's icon (stock id or file name). TOOLTIP is an optional text for the popup help string. The initial value is a command which is run when the button is clicked. Special symbols %N in the command are replaced by the value of field N. If the command starts with @, the output of the command will be parsed and lines started with a number and a colon will be treated as new field values. A quoting style for value when sh -c is used — a single quote around the command and double quotes around the -c argument. The special quit command terminates the dialog in the usual way.
    • FBTN — same as button field, but with full relief of a button.
    • LINK — link button field.
    • LBL — text label. If the field name is empty, a horizontal separator line will be shown.
    • TXT — multiline text entry. This field always occupies all of the form width.

Without a type, the field will be a simple text entry. easy. ✨

  • --align=TYPE — sets the alignment of field labels. Possible types are left, center or right. Default is left.
  • --columns=NUMBER — sets the number of columns in the form. Fields will be placed from top to bottom.
  • --separator=STRING — sets the output separator character. Default is |.
  • --focus-field=NUMBER — sets the focused field.
  • --cycle-read — cycled reading of stdin data. Sending a FormFeed character clears the form. This symbol may be sent as echo -e '\f'. 🌀
  • --align-buttons — aligns the label on button fields according to the --align settings.
  • --item-separator=STRING — sets the separator character for combo-box or scale values. Default is !.
  • --date-format=PATTERN — sets the format for the date fields (same as in the calendar dialog).
  • --float-precision=NUMBER — sets the precision of floating point numbers. By default precision is three digits after the point.
  • --complete=TYPE — uses a specific type for extended completion. TYPE can be any for matching any of the typed words, all for matching all of the typed words, or regex when the typed text is treated as a regular expression.
  • --scroll — makes the form scrollable. for the long forms, we scroll 💅
  • --homogeneous — makes form fields' height and columns' width the same size. symmetrical slay.
  • --changed-action=CMD — runs CMD when a CHK, CB, or SW field value is changed. The command runs with two arguments — the number of the changed field and its current value. The output of the command is parsed in the same manner as in BTN fields with the @ prefix. Attention — this option may slow down your dialog. 😭 you've been warned.
  • --quoted-output — output values will be in shell-style quotes.
  • --output-by-row — outputs field values row by row if several columns are specified.
  • --num-output — outputs the index of the active element instead of the text, for combo-box fields.

because sometimes the form fields need a little pre-filled lore, bestie 💅 Any extra data you tack on the command line gets read as default values for the form fields. And ooh, a special value: @disabled@ makes the corresponding field inactive — like, it's there but it's not participating ✨

If you don't pass any extra arguments on the command line, the data gets read from stdin, one value per line. And "cycled reading" means that for N fields, the N+1th value will replace the first field — the cycle continues, no cap 🔁 Empty values get skipped when reading from stdin, so don't stress about blank lines.

🌐 HTML OPTIONS 🌐

  • --uri=URI — opens the location you point at. URI can be a filename or an internet address. If the URI isn't an existing file and no protocol is specified, a http:// prefix gets added to the URI for you, so generous 🫶
  • --browser — turns on browser mode. In this mode every clicked link opens inside the html widget, and the command Open gets added to the context menu.
  • --print-uri — prints clicked links to standard output. By default, clicked links open with xdg-open.
  • --mime=MIME — sets the mime type of the data passed to standard input to MIME. Default is text/html.
  • --encoding=ENCODING — sets the encoding of the data passed to standard input to ENCODING. Default is UTF-8.
  • --uri-handler=CMD — sets an external handler for clicked URIs. %s gets replaced by the activated URI. The return code of the CMD must be 0 for keep working, 1 for ignoring the URI, and 2 for downloading the URI. This option only works in browser mode, iykyk. There are two environment variables available in the handler: YAD_HTML_BUTTON with the value of the pressed mouse button, and YAD_HTML_STATE with the value of a bitmask with the state of the modifier keys 🔥
  • --user-agent=STRING — sets the user agent string. Default is YAD-Webkit (@VERSION@).
  • --user-style=STRING — loads custom custom user styles from a file or arbitrary data (yes, "custom custom," it said what it said 💀). STRING may be a path to a local file with CSS code or the CSS code itself.
  • --disable-search — disables the search bar.
  • --file-op — enables file operations. This option adds an open menu item to the popup menu,
  • --wk-prop=PROP — sets an additional WebKit setting. This option may be used multiply times. Setting PROP must be in the form "setting-name value". The first character of the value must be a type identifier: b for booleans, i for integers, and s for strings. The values themselves follow after a colon. List of possible settings can be found on this page — https://webkitgtk.org/reference/webkit2gtk/stable/WebKitSettings.html 🌈

When the dialog works in browser mode, additional data on the command line is interpreted as a URI.

📋 LIST OPTIONS 📋

  • --column=STRING[:TYPE] — sets the column header. Types are TEXT, NUM, SZ, FLT, CHK, RD, BAR, IMG, HD or TIP. TEXT type is default. Use NUM for integers and FLT for double values. TIP is used for defining a tooltip column. SZ is a size column type — works exactly like a NUM column but shows human readable sizes instead of numbers, aesthetic ✨ CHK (checkboxes) and RD (radio toggle) are boolean columns. BAR is a progress bar column — value must be between 0 and 100, and if the value is outside the range it will be cropped to the nearest legal value. HD type means a hidden column; such columns aren't displayed in the list, only in the output, sneaky 👀 IMG may be a path to an image or an icon name from the current GTK+ icon theme. Size of icons may be set in the gtk config file at the GTK_ICON_SIZE_MENU position of gtk-icon-sizes. Images specified by icon names will be scaled to GTK_ICON_SIZE_MENU until --force-icon-size is not sets. Image field prints as empty value.

Special column names @fore@, @back@ and @font@ set corresponding row attributes — and values of those columns don't show in results, they're just here for the vibes 🎨

Column title can be specified in the form name!tooltip and Pango markup can be used in the name and tooltip parts. Slay.

  • --tree — enables tree mode. In this mode extra data in the form ROW_ID[:PARENT_ID] must be passed to yad before each row. See EXAMPLES for details 🌳
  • --checklist — uses check boxes for the first column. Outputs checked rows instead of selected rows. Disables multiple selection.
  • --radiolist — same as --checklist but with a radio toggle for the first column.
  • --separator=STRING — sets the output separator characters.
  • --multiple — allows multiple rows to be selected.
  • --editable — allows changes to text.
  • --editable-cols=LIST — sets the list of editable columns. LIST must be a string of numbers separated by commas.
  • --no-headers — does not show column headers.
  • --no-click — disables sorting of column content by clicking on its header.
  • --no-rules-hint — doesn't draw even and odd rows in different colors. This option depends on your current gtk theme and may not work (rude, but ok 😭).
  • --grid-lines=TYPE — draws grid lines of type TYPE in the list dialog. TYPE can be one of hor[izontal], vert[ical] or both.
  • --no-selection — disables selection in the list.
  • --print-all — prints all data from the list.
  • --print-column=NUMBER — specifies what column will be printed to standard output. 0 may be used to print all columns (this is the default).
  • --hide-column=NUMBER — hides a specific column.
  • --expand-column=NUMBER — sets the column expandable by default. 0 sets all columns expandable.
  • --search-column=NUMBER — sets the quick search column. 0 means to disable searching. By default search is made on the first column.
  • --tooltip-column=NUMBER — sets the column with popup tooltips.
  • --sep-column=NUMBER — sets the row separator column. If the cell value from this column equals the specified row separator value, that row will be drawn as a separator. Separator value must be set.
  • --sep-value=TEXT — sets the TEXT as a row separator value. This feature highly depends on your current GTK+ theme and may not work properly.
  • --limit=NUMBER — sets the number of rows in the list dialog. Only the last NUMBER rows will be shown. This option will take effect only when data is reading from stdin.
  • --wrap-width=NUMBER — sets the width of a column before wrapping to NUMBER.
  • --wrap-cols=LIST — sets the list of wrapped columns. LIST must be a string of numbers separated by commas.
  • --ellipsize=TYPE — sets ellipsize mode for text columns. TYPE may be NONE, START, MIDDLE or END.
  • --ellipsize-cols=LIST — sets the list of ellipsized columns. LIST must be a string of numbers separated by commas.
  • --dclick-action=CMD — sets the CMD as a double-click command. When the user double-clicks on a row, CMD will be launched with values of all columns as arguments. By default, double-click selects the row and acts as an OK button for simple lists, sets the checkbox if --checklist is specified, and does nothing when the list runs with --multiple option. When double-click is specified, Enter acts as a double-click and Ctrl+Enter acts as an OK button. CMD may contain a special character %s for setting a position for arguments; by default arguments will be concatenated to the end of CMD. If CMD starts with @, its output will replace values of the current row — main character energy, honestly 👑 This option doesn't work with --editable.
  • --select-action=CMD — sets the CMD as an action when selection is changed. CMD will be launched with values of all columns as arguments. CMD may contain a special character %s for setting a position for arguments; by default arguments will be concatenated to the end of CMD. This option doesn't work with --multiple.
  • --row-action=CMD — sets the CMD as an action when the row is added, modified or removed. The first argument for the command is the name of the action (add, edit or del). The rest of the command line is data from the selected row. Output of this command sets the new row values.
  • --tree-expanded — expands all tree nodes at startup.
  • --regex-search — uses regular expressions in search for text fields.
  • --listen — listens for data from stdin even if command-line values were specified.
  • --quoted-output — output values will be shell-style quoted.
  • --float-precision=NUMBER — sets precision of floating point numbers. By default precision is three digits after the point.
  • --add-on-top — adds new records at the top of the list.
  • --tail, --auto-scroll — autoscrolls to the end of the list when a new row is added.
  • --iec-format — uses IEC (base 1024) units for size values. With this option, values will have suffixes KiB, MiB, GiB 💖
  • --simple-tips — doesn't use markup in tooltips even if the text has valid markup.
  • --header-tips — uses the header name as a fallback tooltip text.
  • --column-align=STRING — sets alignment for columns. STRING must contain an array of letters l, r or c for left, center or right alignment of column content.
  • --header-align=STRING — sets alignment for column headers. STRING same as in --column-align.

Sending the FormFeed character to the list clears it. This symbol may be sent as echo -e '\f' ✨

📑 NOTEBOOK OPTIONS 📑

  • --key=KEY — sets the key of the children.
  • --tab=TEXT — adds a tab with the specified label to the notebook. TEXT may be in the form LABEL[!ICON[!TOOLTIP]] where ! is an item separator. For stack mode, TEXT for label is used as is.
  • --tab-pos=TYPE — sets the tabs position. Value may be top, bottom, left, or right. Default is top. For stack mode, only top or bottom positions are available.
  • --tab-borders=NUMBER — sets the border width around the widget in tabs.
  • --active-tab=NUMBER — sets the active tab.
  • --expand — expands all tabs to the full width of a dialog window.
  • --stack — uses stack mode (GtkStack instead of GtkNotebook).

See the NOTEBOOK and PANED section for more about the notebook dialog 🫶

🔔 NOTIFICATION OPTIONS 🔔

  • --command=CMD — sets the command running when clicked on the icon. Default action is quit if --listen isn't specified.
  • --listen — listens for commands on stdin. See the NOTIFICATION section.
  • --menu=STRING — sets the initial menu for right-click.
  • --separator=STRING — sets the separator character for menu values. Default is |.
  • --item-separator=STRING — sets the separator character for menu items. Default is !.
  • --no-middle — disables exit on middle click.
  • --hidden — doesn't show the icon at startup.
  • --icon-size=SIZE — Sets the notification icon size to SIZE. Heads up: this one doesn't work for themed icons, bestie.

See the NOTIFICATION section for more about separators.

🧚 Appindicator options

  • --listen — Listens for commands on stdin. Peep the NOTIFICATION section for the deets.
  • --menu=STRING — Sets the initial menu for right-click. Very right-click slay.
  • --separator=STRING — Sets the separator character for menu values. Default is |.
  • --item-separator=STRING — Sets the separator character for menu items. Default is !.
  • --hidden — Doesn't show the icon at startup. Mysterious. Iconic. Incognito vibes.

🦋 Paned options

  • --key=KEY — Sets the key of the children.
  • --orient=TYPE — Sets the orientation of panes inside the dialog. TYPE may be hor[izontal] or vert[ical].
  • --splitter=POS — Sets the initial splitter position.
  • --focused=PANE — Sets the pane for initial focus. PANE must be 1 or 2. Default is 1.

See the NOTEBOOK and PANED section for more about the paned dialog.

🌸 Picture options

  • --size=VALUE — Sets the initial size of the picture. Available values are fit for fitting the image in the window, or orig for showing the picture in original size.
  • --inc=NUMBER — Sets the increment value for scaling the image.
  • --filename=FILENAME — Sets the picture filename. If no filename is specified, extra data will be used. In that case, several filenames can be specified.
  • --file-op — Enables file operations. This option adds an open menu item to the popup menu.
  • --image-changed=CMD — Sets the command that runs after changing the image. The argument of the command is the filename of the current image. The argument can be specified by the '%s' pattern, or it will be the last part of the command.

Some actions on a picture — like navigation, scaling, or rotating — are available from the popup menu. Those actions can be made only on static images. No moving-picture chaos allowed.

  • --transparent=PERCENT — Makes the popup window transparent.
  • --timeout=TIMEOUT — Changes the default timeout. By default, timeout is 300 seconds.
  • --keep — Don't close the popup window automatically. By default, the window will be closed after TIMEOUT seconds.
  • --align=TYPE — Sets the alignment of the popup title and text. TYPE can be one of left, center, or right.
  • --type=TYPE — Sets the source file type. TYPE may be TEXT for text files, IMAGE for image files, or RAW for files in postscript or pdf formats.
  • --filename=FILENAME — Sets the name or path to the source file.
  • --headers — Adds headers to the top of the page with filename and page number. This option doesn't work for RAW type.
  • --add-preview — Adds a Preview button to the print dialog. This option doesn't work for RAW type.
  • --fontname=FONTNAME — Sets the font for printing text. FONTNAME is a string with font representation in the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]". This option works only for TEXT type.

📊 Progress options

When the --progress option is used, yad reads lines of progress data from stdin. When the lines begin with #, the text after # is displayed in the progress bar label. Numeric values are treated like percentages for the progress bar.

  • --bar=LABEL[:TYPE] — Adds a progress bar. LABEL is a text label for the progress bar. TYPE is a progress bar type. Types are: NORM for normal progress bar, RTL for inverted progress bar, PULSE for pulsate progress bar, and CPULSE for continuous pulsating progress bar. If no bars are specified, the progress dialog works in single-bar mode.
  • --vertical — Sets vertical orientation of progress bars.
  • --align=TYPE — Sets alignment of bar labels. Possible types are left, center, or right. Default is left.
  • --progress-text=TEXT — Sets the label of the progress bar to TEXT. This option works only in single-bar mode.
  • --hide-text — Hides text in progress bars.
  • --rtl — Sets Right-To-Left progress bar direction. This option works only in single-bar mode.
  • --auto-close — Closes the dialog when 100% has been reached.
  • --auto-kill — Kills the parent process if the cancel button is pressed.
  • --pulsate — Pulsates the progress bar. This option works only in single-bar mode.
  • --continuous — Continuously pulsating progress bar. This option works only in single-bar mode.
  • --scroll — Makes the layout scrollable.
  • --enable-log[=TEXT] — Shows the log window. This window gathers all of the lines from stdin that start with #, instead of setting the appropriate progress text. Optional argument TEXT is a text label for the window expander.
  • --log-on-top — Places the log window above progress bars.
  • --log-expanded — Starts with the log window expanded.
  • --log-height — Sets the height of the log window.

Initial values for bars are set as extra arguments. Each line with progress data passed to stdin must start with N:, where N is the number of the progress bar. In single-bar mode, N: is not needed. Easy peasy.

📝 Text info options

  • --filename=FILENAME — Opens the specified file.
  • --editable — Allows changes to the text.
  • --wrap — Enables text wrapping.
  • --formatted — Enables Pango markup. This option doesn't work with the --editable option.
  • --justify=TYPE — Sets justification. TYPE may be left, right, center, or fill. Default is left.
  • --margins=NUMBER — Sets text margins to NUMBER.
  • --tail | --auto-scroll — Autoscrolls to the end when new text appears. This option works only when text is read from stdin.
  • --line=NUMBER — Jumps to a specific line at startup. This option works only when a filename was specified.
  • --show-cursor — Shows the cursor in read-only mode.
  • --show-uri — Makes links in the text clickable. Links open with the xdg-open command.
  • --fore=COLOR — Sets the default color for text.
  • --back=COLOR — Sets the default color for the background.
  • --uri-color=COLOR — Sets the color for links. Default is blue.
  • --listen — Listens for data from stdin even if a filename was specified.
  • --in-place — Saves the file on exit instead of printing its content on stdout. This option works only if the file was specified from the command line.
  • --file-op — Enables file operations. This option adds open and save menu items to the popup menu. This option works only in editable mode.
  • --disable-search — Disables the search bar.
  • --confirm-save=[TEXT] — Confirms file saving if the file content was changed. This option works only when --in-place is specified. The optional argument is text for the confirmation dialog.

Next options work only if yad is built with GtkSourceView:

  • --lang=LANGUAGE — Highlights syntax for the specified LANGUAGE.
  • --theme=THEME — Sets the used theme to THEME. Use yad-tools(1) to get a list of all available themes.
  • --mime=TYPE — Specifies the mime type of input data. This option is only needed for guessing appropriate syntax highlighting.
  • --line-num — Shows line numbers.
  • --line-hl — Highlights the current line.
  • --line-marks — Enables line marks mode. There are two types of marks. The first type is set by the left mouse button, and the second by the right mouse button.
  • --mark1-color=COLOR — Sets the background color for marks of the first type to COLOR. Default is lightgreen.
  • --mark2-color=COLOR — Sets the background color for marks of the second type to COLOR. Default is pink.
  • --right-margin=[POS] — Enables the mark of the right margin. Optional argument POS is a margin position in characters. Default is 80.
  • --brackets — Highlights matching brackets.
  • --indent — Enables autoindent. This option also sets the Tab key as the indent key.
  • --smart-he=TYPE — Sets behavior of Home and End keys. The TYPE is one of newer, before, after, or always.
  • --smart-bs — Enables smart mode for BackSpace. If this option is enabled, BackSpace will delete spaces to the next tab position.
  • --tab-width — Sets the tabulation step.
  • --indent-width — Sets the indentation step.
  • --spaces — Inserts spaces instead of tabulation.

If the fontname option is specified for the text dialog, the description of the font must be in CSS style (not in a Pango style). Sending a FormFeed character to the text dialog clears it. This symbol may be sent as echo -e '\f'. Pressing Ctrl+S popups the search entry in the text dialog. Muscle memory, but make it text editor.

⚖️ Scale options

  • --value=VALUE — Sets the initial value.
  • --min-value=VALUE — Sets the minimum value.
  • --max-value=VALUE — Sets the maximum value.
  • --step=VALUE — Sets the step size.
  • --enforce-step — Only allows values in step increments.
  • --page=VALUE — Sets the paging size. By default, the page value is STEP*10.
  • --print-partial — Prints partial values.
  • --hide-value — Hides the value.
  • --vertical — Shows a vertical scale.
  • --invert — Inverts the scale direction.
  • --inc-buttons — Shows buttons on the edges of a scale for increasing or decreasing the scale value.
  • --mark=[NAME]:VALUE — Adds a mark to the scale. May be used multiple times. NAME is an optional argument for setting a label to the mark.

🗂️ File filters options

  • --file-filter=NAME | PATTERN1 PATTERN2 ... — Adds a filename filter. NAME is a displayed filter name, and PATTERN is a shell-style filename pattern (for example *.txt). This option may be used multiple times.
  • --mime-filter=NAME | MIME1 MIME2 ... — Adds a mime-type filter. NAME is a displayed filter name, and PATTERN is the name of a mime type (for example text/plain). This option may be used multiple times.
  • --image-filter=[NAME] — Adds a filter for images supported by the gdk-pixbuf library. NAME is the optional name for this filter.

These options apply to all of yad's file chooser dialogs. Every single one. No filter-less behavior on my watch.

🖼️ File preview options

  • --add-preview — Adds a preview widget. Preview images load from normal (default) or large thumbnails according to the XDG Thumbnails specification v0.8.0 (http://standards.freedesktop.org/thumbnail-spec/latest/), or yad creates them for image files and saves them as normal or large thumbnails.
  • --large-preview — Uses large previews by default. This option can be permanently turned on through yad settings.

These options apply to all of yad's file chooser dialogs.

NOTE: YAD doesn't check mtime for thumbnailed images and doesn't update the preview if the original file was changed after the thumbnail was created. Bestie, the thumbnail can be lying to you.

🌟 Miscellaneous options 🌟

  • -?, --help — shows a lil summary of all the options, bestie 💖
  • --about — pops open an about dialog, very meta
  • --version — shows the version of the program, so you know what you're working with ✨

Also, no cap, the standard GTK+ options are accepted too.

📓 NOTEBOOK and PANED 🪟

Okay so Notebook is this complex dialog that literally swallows other dialogs into its tabs — it's giving main character energy fr. Dialogs get identified by a unique key (an integer, keep it cute) and must be run in that special plug mode (the --plug option).

Here's the iconic example: a notebook dialog with two tabs, where the first has a simple text and the second is an entry dialog.

#! /bin/sh

yad --plug=12345 --tabnum=1 --text="first tab with text" &> res1 &
yad --plug=12345 --tabnum=2 --text="second tab" --entry &> res2 &
yad --notebook --key=12345 --tab="Tab 1" --tab="Tab 2"
NOTE: the order of output results for tabs is undefined! 😭 Do not come for me about the ordering, it's not me it's the tabs.

Paned works in the same manner as a notebook with one restriction — only the first and second plug dialogs will be swallowed into panes. That's it, that's the whole vibe check.

🔔 NOTIFICATION 🔔

This lets commands be sent to yad in the form command:args. The possible commands are icon, tooltip, visible, action, menu and quit. Slay, let's go through them 💅

  • icon:ICONNAME — sets the notification icon to ICONNAME.
  • tooltip:STRING — sets the notification tooltip.
  • visible:[true|false] — sets the notification icon to visible or invisible state. Peekaboo 🫣
  • action:COMMAND — specifies the command that runs when you click on the icon. There are two special commands here: menu for popup user defined menu, and quit for exiting the program.
  • menu:STRING — sets the popup menu for the notification icon. STRING must be in the form name1[!action1[!icon1]]|name2[!action2[!icon2]].... An empty name adds a separator to the menu. The separator character for values (e.g. |) is set with the --separator argument. The separator character for menu items (e.g. !) is set with the --item-separator argument.
  • quit — exits the program. Middle clicking on the icon also sends the quit command. iykyk 🖱️

👑 STOCK ITEMS 👑

This is the list of predefined items available in yad — genuinely iconic lineup:

  • yad-about — label About, icon help-about
  • yad-add — label Add, icon list-add
  • yad-apply — label Apply, icon gtk-apply
  • yad-cancel — label Cancel, icon gtk-cancel
  • yad-clear — label Clear, icon document-clear
  • yad-close — label Close, icon window-close
  • yad-edit — label Edit, icon gtk-edit
  • yad-execute — label Execute, icon system-run
  • yad-no — label No, icon gtk-no
  • yad-ok — label OK, icon gtk-ok
  • yad-open — label Open, icon document-open
  • yad-print — label Print, icon document-print
  • yad-quit — label Quit, icon application-exit
  • yad-refresh — label Refresh, icon view-refresh
  • yad-remove — label Remove, icon list-remove
  • yad-save — label Save, icon document-save
  • yad-search — label Search, icon system-search
  • yad-send — label Send, icon document-send
  • yad-settings — label Settings, icon gtk-preferences
  • yad-yes — label Yes, icon gtk-yes

🌈 ENVIRONMENT VARIABLES 🌈

  • YAD_OPTIONS — this variable can hold some default options for yad. All options in this variable may be redefined from the command line. So the CLI stays the boss, periodt 👑
  • YAD_SETTINGS_FILE — the location of the file with yad settings. See the SETTINGS section for the details.
  • YAD_PID — this variable gets set to the value of the current dialog's pid, and it's accessible in all dialog children.
  • YAD_XID — this variable gets set to the value of the current dialog's X Window ID, and it's accessible in all dialog children. > Heads up bestie: this variable is not set in print and notification dialogs, and not in dialogs which act as notebook or paned children. 🫶

💀 USER DEFINED SIGNALS 💀

  • SIGUSR1 — closes the dialog with a 0 exit code.
  • SIGUSR2 — closes the dialog with a 1 exit code.

Send the right signal, get the right exit code. Fr fr 🔥

🚪 EXIT STATUS 🚪

  • 0 — the user has pressed the OK button
  • 1 — the user has pressed the Cancel button
  • 70 — the dialog has been closed because the timeout has been reached.
  • 252 — the dialog has been closed by pressing Esc or by using the window functions to close the dialog

Exit codes for user-specified buttons must be specified in the command line. An even exit code means to print the result, an odd one just returns the exit code. That's the whole rule, no cap ✨

🎀 WIDGETS NAMES 🎀

The look and feel of yad's dialogs can be customized through a gtkrc file. Here are the names of yad's widgets — every single one, I'm not skipping anybody 💜

  • yad-dialog-window — GtkDialog — Dialog window
  • yad-dialog-image — GtkImage — Dialog image
  • yad-dialog-label — GtkLabel — Dialog text
  • yad-app-widget — GtkAppChooserWidget — Application selection widget
  • yad-calendar-widget — GtkCalendar — Calendar widget
  • yad-color-widget — GtkColorChooser — Color selection widget
  • yad-color-palette — GtkTreeView — Predefined colors list
  • yad-entry-label — GtkLabel — Entry label
  • yad-entry-widget — GtkEntry — Entry widget
  • yad-entry-spin — GtkSpinButton — Entry widget for numeric values
  • yad-entry-combo — GtkComboBox — Entry widget with combo
  • yad-entry-edit-combo — GtkComboBoxEntry — Entry widget with editable combo
  • yad-file-widget — GtkFileChooser — File selection widget
  • yad-font-widget — GtkFontChooser — Font selection widget
  • yad-form-flabel — GtkLabel — Field label in form
  • yad-form-button — GtkButton — Button field in form
  • yad-form-entry — GtkEntrfy — Entry field in form
  • yad-form-spin — GtkSpinButton — Numeric entry field in form
  • yad-form-check — GtkCheckButton — Checkbox field in form
  • yad-form-combo — GtkComboBox — Combo field in form
  • yad-form-edit-combo — GtkComboBoxEntry — Editable combo field in form
  • yad-form-link — GtkLinkButton — Link field in form
  • yad-form-file — GtkFileChooserButton — File or directory field in form
  • yad-form-font — GtkFontChooserButton — Font field in form
  • yad-form-app — GtkAppChooserButton — Application field in form
  • yad-form-switch — GtkSwitch — Switch field in form
  • yad-form-color — GtkColorChooserButton — Color field in form
  • yad-form-label — GtkLabel — Label field in form
  • yad-form-scale — GtkScale — Scale widget in form
  • yad-form-separator — GtkSeparator — Separator in form
  • yad-form-text — GtkTextView — Multiline text field in form
  • yad-icons-full — GtkIconView — Icons widget for normal mode
  • yad-icons-compact — GtkTreeView — Icons widget for compact mode
  • yad-list-widget — GtkTreeView — List widget
  • yad-notebook-widget — GtkNotebook — Notebook widget
  • yad-paned-widget — GtkPaned — Horizontal or vertical pane widget
  • yad-progress-widget — GtkProgressBar — Progressbar widget
  • yad-scale-widget — GtkScale — Scale widget
  • yad-stack-widget — GtkStack — Stack widget
  • yad-stack-switcher-widget — GtkStackSwitcher — Stack switcher widget
  • yad-text-widget — GtkTextView — Text info widget
  • yad-timeout-indicator — GtkProgreeBar — Timeout indicator

(Yes, GtkEntrfy and GtkProgreeBar are written exactly like that in the list. Copy them as-is if you're matching against them, bestie — do not "fix" them 😭)

⚙️ SETTINGS ⚙️

YAD reads some defaults from a settings file. This file may be created with the --write-settings argument. The syntax of this file is a simple ini-style. Default location is $XDG_CONFIG_HOME/yad/settings.conf, and it can be redefined with the YAD_SETTINGS_FILE environment variable. Easy 🎀

✨ EXAMPLES ✨

Okay these are the fun ones, let's go 🦋

Display a file selector with the title Select a file to remove. The file selected is returned on standard output.

yad  --title="Select a file to remove" --file-selection

Display a text entry dialog with the title Select Host and the text Select the host you would like to flood-ping. The entered text is returned on standard output.

yad  --title "Select Host" --entry --text "Select the host you would like to flood-ping"

Display a dialog asking Microsoft Windows has been found! Would you like to remove it?. The return code will be 0 (true in shell) if YES is selected, and 1 (false) if NO is selected. Not me making the whole thing a threat 💀

yad  --image "dialog-question" --title "Alert" --button=gtk-yes:0 --button=gtk-no:1 --text "Microsoft Windows has been found! Would you like to remove it?"

Show the search results in a list dialog with the title Search Results and the text Finding all header files....

find . -name '*.h' | yad --list --title "Search Results" --text "Finding all header files.." --column "Files"

Show an icon in the notification area

yad --notification --image=update.png --text "System update necessary!" --command "xterm -e apt-get upgrade"

Display a weekly shopping list in a check list dialog with Apples and Oranges pre selected 🍎🍊

yad --list --checklist --column "Buy" --column "Item" TRUE Apples TRUE Oranges FALSE Pears FALSE Toothpaste

Display a progress dialog while searching for all the postscript files in your home directory

find $HOME -name '*.ps' | yad --progress --pulsate

Display a box with all of the installed desktop applications

yad --icons --read-dir=/usr/share/applications

Display list in tree mode

yad --list --tree --column "Items" f Fruits 1:f Apple 2:f Lemon v Vegetables 3:v Popato 4:v Onion

(Popato stays a popato. It's in the original, I don't make the rules 🥔💅)

🛠 DEVELOPMENT 🛠

There are some developers features provided with YAD — for the build girlies 🧚

YAD icon browser is a graphical tool for discovering icons in the current or a user-specified GTK+ icon theme. Launch it as:

yad-icon-browser [theme]

When using autoconf you may use the special m4 macro AM_PATH_YAD for looking for yad and checking its version. Usage of this macro is:

AM_PATH_YAD([MINIMUM-VERSION],\ [ACTION-IF-FOUND],\ [ACTION-IF-NOT-FOUND])

🫶 AUTHORS 🫶

Yad was written by Victor Ananjevsky <ananasik@gmail.com>. Yad icon created by Bogdan Lisovich. Absolute legends, we stan 👑💖

🌈 SEE ALSO 🌈

okay so you've absorbed the whole entire manual (iconic of you, fr) — here's the rest of the friend group, the other pages you might wanna go read next bestie 💖

  • gdialog(1) — the other dialog-flavoured cousin, go say hi 🫶
  • dialog(1) — like, the original OG terminal-dialog situation, the blueprint, the blueprint-est 💅
  • zenity(1) — the other GUI-dialog girlie, you know the one, we don't compete we just coexist ✨
  • yad-tools(1) — the companion page for the yad-tools stuff, highkey go check it out 👑
not to be dramatic but you literally read the whole page and that's main character energy, no cap 🎀

and that's a wrap on the whole thing, bestie 🦋 this page came from the yad source, dated June 2024, and it lives in section YAD(1) of the manual — so like, that's its whole little home 🏠💜 you're so welcome, go make some gorgeous dialogs, slay, periodt 🌸💅

📦 where this page comes from