Dialog is configurable through command line options. All options can also be specified using JSON configuration.
dialog --title "Hello" --message "World"
Use --help <option> for detailed information about a specific argument.
| Argument | Short | Description |
|---|
--title <text> | -t | Set the dialog title. Use none to hide. |
--subtitle <text> | | Secondary line of text displayed below the title. Also used as subtitle text for notifications. |
--message <text> | -m | Set the dialog message. Supports Markdown. |
--messagealignment [left|centre|right] | | Horizontal alignment of the message |
--messageposition [top|centre|bottom] | | Vertical position of the message content block |
--titlefont <params> | | Modify title font. Accepts comma-separated key=value pairs: colour, size, weight, name, alignment, offset, shadow |
--messagefont <params> | | Modify message font (color, size) |
See Title and Message for details.
| Argument | Short | Description |
|---|
--icon <file|url> | -i | Set the dialog icon. Accepts file path, URL, SF Symbol (SF=name), or info|caution|warning |
--iconsize <num> | | Icon size in points (default: 150) |
--iconalpha <num> | | Icon opacity from 0.0 (transparent) to 1.0 (opaque) |
--iconalttext <text> | | Accessibility label for the icon |
--overlayicon <file|url> | -y | Overlay image displayed at bottom-right of icon |
--hideicon | -h | Hide the icon to increase message area |
--centreicon / --centericon | | Reposition icon to centre between title and message |
See Icon for details.
| Argument | Short | Description |
|---|
--bannerimage <file|url> | -n | Display a banner image at the top of the dialog |
--bannertitle <text> | | Display title text overlaid on the banner |
--bannertext <text> | | Equivalent to setting --bannertitle and --title |
--bannerheight <num> | | Set the banner height |
--background <file> | -bg | Set a background/watermark image |
--bgalpha <num> | -ba | Background image opacity (default: 0.5) |
--bgposition <position> | -bp | Background image position (e.g. center, topleft) |
--bgfill [fill|fit] | -bf | Background image fill mode |
--bgscale [fill|fit] | -bs | Background image scale mode |
See Banner Images and Background Images for details.
| Argument | Short | Description |
|---|
--button1text <text> | | Label for Button 1 (bound to Return ↵, default: OK) |
--button1action <url> | | URL to open when Button 1 is clicked |
--button1shellaction <cmd> | | Shell command to run when Button 1 is clicked |
--button1symbol <sf symbol> | | SF Symbol to display on Button 1 |
--button1disabled | | Launch with Button 1 disabled |
--button2 | -2 | Show Button 2 |
--button2text <text> | | Label for Button 2 (bound to Esc ⎋, default: Cancel) |
--button2symbol <sf symbol> | | SF Symbol to display on Button 2 |
--button2disabled | | Launch with Button 2 disabled |
--infobutton | -3 | Show the info button |
--infobuttontext <text> | | Label for the info button |
--infobuttonaction <url> | | URL to open when the info button is clicked |
--infobuttonsymbol <sf symbol> | | SF Symbol to display on the info button |
--buttonstyle [center|stack] | | Button layout style |
--buttonsize [mini|small|regular|large] | | Button size |
--buttontextsize <num> | | Button label font size |
--quitoninfo | | Quit dialog when info button is selected |
See Buttons for details.
| Argument | Short | Description |
|---|
--helpmessage <text> | | Show a help button with popover content. Supports Markdown. |
--helpimage <file|url> | | Add an image to the help popover |
--helpsheetbuttontext <text> | | Label for the help sheet dismiss button (default: OK) |
--helpalignment [left|centre|right] | | Alignment of help message content |
See Help Message for details.
| Argument | Short | Description |
|---|
--image <file|url> | -g | Display an image. Multiple instances create a carousel. |
--imagecaption <text> | | Caption displayed below the image |
--video <file|url> | | Display a video. Supports youtube=<id> and vimeo=<id> shortcuts. |
--videocaption <text> | | Caption displayed below the video |
--autoplay | | Autoplay video on launch |
--webcontent <url> | | Display a web page in the message area |
See Images, Video, and Web Content for details.
| Argument | Short | Description |
|---|
--infotext <text> | | Replace the info button with static text |
--infobox <text> | | Display text (Markdown supported) below the icon |
See Info Box for details.
| Argument | Short | Description |
|---|
--textfield <text>[,options] | | Add a text input field. Supports required, secure, prompt, regex, fileselect and more. |
--textfieldlivevalidation | | Show live regex validation feedback on text fields |
--checkbox <text> | | Add a checkbox with the given label |
--checkboxstyle [checkbox|switch][,size] | | Change checkbox appearance |
--selecttitle <text>[,options] | | Add a dropdown select list with the given name |
--selectvalues <csv> | | Comma-separated values for the select list |
--selectdefault <text> | | Default selected value for the select list |
--selectstyle | | Style for the select list |
See Text Fields, Checkboxes, and Select Lists for details.
| Argument | Short | Description |
|---|
--listitem <text> | | Add a list item. Supports status icons and click actions. |
--liststyle [expanded|compact] | | Vertical spacing between list rows |
--enablelistselect | | Allow list items to be selected; selection is returned on exit |
See Item Lists for details.
| Argument | Short | Description |
|---|
--timer [<seconds>] | | Show a countdown timer (default: 10s). Exits with code 4 on timeout. |
--hidetimerbar | | Hide the timer bar while still counting down |
--hidetimer | | Hide the timer completely |
--progress [<int>] | | Show a progress bar with the specified number of steps |
--progresstext <text> | | Initial text shown below the progress bar |
See Timer & Progress for details.
| Argument | Short | Description |
|---|
--width <num> | | Dialog window width in points |
--height <num> | | Dialog window height in points |
--small | -s | Decrease default window size by 25% |
--big | -b | Increase default window size by 25% |
--position <position> | | Window position (e.g. center, topright, or x,y) |
--positionoffset <int> | | Edge offset when using --position (default: 16) |
--moveable | -o | Allow the window to be dragged |
--resizable | | Allow the window to be resized (implies --moveable) |
--ontop | -p | Keep the window above all other windows |
--windowbuttons [close,min,max] | | Enable window close/minimise/maximise buttons |
--showonallscreens | | Show the window on all connected screens |
--appearance [dark|light] | | Override the window appearance |
See Window Size and Layout for details.
| Argument | Short | Description |
|---|
--style <preset> | | Apply a preset style: presentation, mini, centered, alert, caution, warning |
--mini | | Compact window showing title, icon and a two-line message |
--fullscreen | -f | Full-screen mode (no buttons; keyboard events still work) |
--presentation | | Presentation mode with progress bar and structured layout |
--eula | | Display in EULA acceptance mode |
--blurscreen | | Blur all screen content behind the dialog window |
--hideotherapps | | Hide all other apps on launch |
See Full Screen and Presentation for details.
| Argument | Short | Description |
|---|
--notification | | Send a macOS system notification |
--identifier <text> | -id | Unique identifier for the notification |
--remove | | Remove the notification with the matching --identifier |
--enablenotificationsounds | | Enable notification sounds |
See Notifications for details.
| Argument | Short | Description |
|---|
--sound <file|url> | | Play an audio file on launch |
--showsoundcontrols | | Show playback controls (play/pause, mute, timeline) |
| Argument | Short | Description |
|---|
--showdockicon | | Show the Dialog icon in the macOS Dock |
--dockicon <file|url> | | Show a custom image as the Dock icon (implies --showdockicon) |
--dockiconbadge <text> | | Display a badge on the visible Dock icon |
| Argument | Short | Description |
|---|
--commandfile [<file>] | | Path to the command file for live dialog updates (default: /var/tmp/dialog.log) |
--displaylog <file> | | Display the contents of a file as it is written |
--loghistory [<int>] | | Pre-populate --displaylog with the last N lines (default: 100) |
See Command File for details.
| Argument | Short | Description |
|---|
--jsonfile <file> | | Load dialog configuration from a JSON file |
--jsonstring <text> | | Load dialog configuration from a JSON string |
--json | -j | Output results in JSON format |
See JSON Configuration for details.
| Argument | Short | Description |
|---|
--quitkey <char> | | Custom quit key (used as ⌘ + <key>, default: q) |
--hidedefaultkeyboardaction | | Require ⌘ + ⇧ to trigger Return/Esc keyboard actions |
--alwaysreturninput | | Always return user input on exit regardless of exit code |
--ignorednd | -d | Display dialog even when Do Not Disturb is active |
--vieworder <csv> | | Override the display order of input element types |
| Argument | Short | Description |
|---|
--key <string> | -k | Authentication key required to launch dialog |
--checksum <string> | | Generate a SHA256 hash (for use with --key) |
See Authorization for details.
| Argument | Short | Description |
|---|
--loginwindow | | Show the dialog at login window (requires appropriate LaunchAgent) |
See Login Window for details.
| Argument | Short | Description |
|---|
--inspect-mode | | Launch in inspect mode |
--inspect-config <file> | | Specify configuration for inspect mode |
--inspect-schema <file> | | Specify schema for inspect mode |
--schema-validate <file> | | Validate a configuration against a schema |
See Inspect Mode for details.
| Argument | Short | Description |
|---|
--version | -v | Print the version string |
--help [<argument>] | | Print help, or detailed help for a specific argument |
--licence | -l | Print the license |
--debug [<colour>] | | Enable debug mode with optional content boundary highlights |
--verbose | -vvv | Enable verbose log output |
--listfonts | | Print available font names |
--demo | | Launch in demo mode |
--builder | | Launch the construction kit UI |
--jh | -jh | Enable jamfHelper compatibility mode |
See Builder for details.
