CLI Reference

CLI Reference

The executable is dialog.exe. Every option below is enumerated from the argument parser in src/csharpDialog.Core/CommandLineParser.cs; nothing here is inferred from the README.

dialog [options]

How arguments are parsed

The parser walks args left to right. Each token is lowercased before matching, so --TITLE, --Title and --title are the same flag. Values are not lowercased.

Behaviour	Consequence for scripts
Flags are matched case-insensitively	--fullScreen works
A value-taking flag consumes the next token verbatim	Quote values containing spaces; the parser does not understand --title=Hello
An unrecognised token is silently skipped	A typo, or a flag that only exists in older docs (--progressbar, --debug), produces no error and no effect
A numeric flag whose next token does not parse as an integer does not consume it	--progress alone is valid and just turns the bar on
Repeating --button1 adds a second button entry	Pass each button flag once
--listitem may be repeated	Items appear in the order given
If no button flag is given, a default button OK (action ok) is added	The dialog always has one button

There is no -- end-of-options separator, no response file, and no environment-variable form of any flag.

Choosing a front end

dialog.exe picks its front end from the flags it was given. This is the single most common source of "it printed to the console instead of opening a window":

Condition	Front end
Any of --window, --fullscreen, --kiosk, --firstrun, --autolaunch, or --commandfile present	WPF window (ProgressDialogWindow)
None of the above	Console fallback: the title, message, list and buttons are printed to stdout and the process waits on Console.ReadLine()

The console fallback is also used if the WPF assembly cannot be loaded. It is a genuine interactive prompt, not a rendering — it blocks reading a menu selection from stdin, which will hang a non-interactive script.

The WPF window that dialog.exe shows is a fixed layout: header (built-in graphic + title), message, scrolling list, progress caption, progress bar, one right-aligned button. Flags that would restyle a window it does not draw are listed as inert below.

Content

Flag	Alias	Type	Default	Effect
--title	-t	string	empty	Window caption and the large header text
--message	-m	string	empty	Body text under the header; wraps, honours 
 newlines from the shell
--icon	-i	path	empty	Parsed and stored. Inert in dialog.exe — the window's header graphic is a built-in vector and is never replaced. Applied only by the separate csharpDialog.WPF.exe host
--image		path	empty	Parsed and stored. Inert in dialog.exe, same reason as --icon
--video		path	empty	Parsed and stored. No playback exists anywhere in the codebase; the csharpDialog.WPF.exe host only un-hides an empty placeholder
--markdown		switch	off	Parsed into EnableMarkdown and never read by anything. Message text is rendered as a plain TextBlock. There is no markdown support

Buttons

Flag	Alias	Type	Default	Effect
--button1	--button1text	string	OK	Text of the dialog's single button. Marked as the default button; its action is button1
--button2	--button2text	string	none	Adds a second button to the configuration with action button2. The dialog.exe window has only one button control, so this text is never displayed. It still affects nothing at exit because only the visible button can be clicked
--button1disabled		switch	off	Renders button1 disabled and engages a close lock: the title-bar X and Alt+F4 are refused. The window can then only be dismissed by a quit command, the quit key, a timeout, or a later button1: enable command

Dismissal and keyboard control

Flag	Type	Default	Effect
--quitkey	single char	none	Ctrl+<char> closes the dialog. Only the first character of the value is used. Letters A–Z and digits 0–9 are recognised; other characters never match. Closing this way reports quit
--hidedefaultkeyboardaction	switch	off	Swallows Esc, Enter/Return and Alt+F4 in the dialog
--timeout	integer seconds	none	Auto-closes the window after N seconds. The timer starts when the window is created, not when it becomes visible. Closing this way reports timeout

--quitkey is the Windows analogue of swiftDialog's Cmd-based quit key; the modifier here is Ctrl.

Progress

Flag	Type	Default	Effect
--progress	switch, optional integer	bar hidden	Shows the progress bar. If the next token parses as an integer it is stored as the initial value — but the dialog.exe window does not apply the stored initial value; the bar starts where its XAML left it. Drive it from the command file instead
--progress-max	integer	100	Stored as the maximum. Inert in dialog.exe — the bar's maximum is fixed at 100. Treat every progress: value as a percentage
--progresstext	string	empty	Shows the progress bar and stores the caption. As with --progress, the initial caption is not applied by dialog.exe; send progresstext: through the command file

The practical rule: use --progress (no value) to make the bar visible at launch, and set value and caption over the command file.

List items

Flag	Type	Default	Effect
--listitem	string	none	Adds one row to the list and makes the list visible. Repeatable. Initial items are rendered at launch

The value is a comma-separated triple, all parts after the first optional:

--listitem "Title"
--listitem "Title,status"
--listitem "Title,status,iconpath"

status is one of none, wait, success, fail, error, pending, progress (case-insensitive; anything unrecognised becomes none). iconpath must be an existing absolute file path to an image — a relative path, a URL, or an emoji is accepted by the parser but silently fails to load, leaving the coloured status dot in place.

Because the separator is a comma, a list item title containing a comma cannot be expressed on the command line. Add such items over the command file, where title: takes everything up to the next comma, or avoid commas in titles.

Status rendering in the window:

Status	Indicator
success	Green dot
wait	Orange dot
fail, error	Red dot
pending, progress	Animated blue spinner
none / anything else	Grey dot

The emoji glyphs (⏳ ✅ ❌ ⚠️ 🔵 🔄) defined in StatusIconProvider are used by the console fallback and by ToString() diagnostics, not by the WPF window.

Window mode and geometry

Flag	Type	Default	Effect
--window	switch	off	Forces the WPF window and explicitly overrides --fullscreen and --kiosk if they were also passed
--fullscreen	switch	off	Hosts the dialog centred inside a full-virtual-desktop overlay with a dimmed, DWM-blurred backdrop. Also sets topmost
--kiosk	switch	off	Implies --fullscreen, and additionally cancels window-close attempts so the user cannot dismiss it. Requires a quit command (or a timeout) to exit
--width	integer px	750	Sets window width and turns auto-sizing off
--height	integer px	1000	Sets window height and turns auto-sizing off
--centeronscreen	switch	on already	Parsed. The dialog.exe window is centred by its XAML regardless, so this flag changes nothing there
--topmost	switch	off	Parsed. Inert in dialog.exe — the window's topmost state comes from its XAML (False) and is not overwritten. The fullscreen overlay is always topmost, so --fullscreen is the way to stay in front

The overlay caps the hosted dialog at 850 × 1200 logical pixels, so --width/--height beyond that are clipped in fullscreen and kiosk mode.

Styling

All four styling flags are parsed into the configuration and are inert in dialog.exe. The window follows the system light/dark setting instead, read from HKCU\Software\Microsoft\Windows\CurrentVersion\Themes\Personalize\AppsUseLightTheme, including an immersive dark title bar via DWM. They are honoured only by the separate csharpDialog.WPF.exe host.

Flag	Type	Default
--backgroundcolor	hex colour string	#f8f9fa
--textcolor	hex colour string	#2c3e50
--fontfamily	font family name	Segoe UI
--fontsize	integer	14

Live updates

Flag	Type	Default	Effect
--commandfile	path	none	Creates the file (and its directory) if absent, then watches it and applies every command line appended to it. Also forces the WPF front end

Monitoring starts about one second after the window is created, and the file is read from offset zero, so commands written before the dialog launches are still applied. See Command File Reference.

Management integration

Flag	Alias	Type	Effect
--cimian	--cimianmonitor	switch	Starts the Cimian log monitor alongside the dialog: tails the client's run log, seeds the list from cached manifests, and updates rows as installs start and finish
--firstrun		switch	First-run preset: topmost, progress bar on, list on. Marks first-run complete in the registry when the dialog closes
--autolaunch		switch	Runs first-run detection first and exits 0 doing nothing if this is not a first-run scenario. Used as the whole argument list (dialog --autolaunch) it also applies a built-in title, message and kiosk preset

--autolaunch behaves differently depending on whether it is the only argument. Alone it takes a dedicated code path with its own hardcoded configuration; combined with other flags it only adds the first-run gate to whatever you configured. Details in Cimian Integration.

Help

Flag	Alias	Effect
--help	-h	Prints the built-in usage text to stdout and exits 0 immediately, ignoring any other flags

Exit codes

The exit code is derived from which dismissal path closed the window:

Situation	Reported result	Exit code
The button was clicked and no --button1 was given	ok	0
The button was clicked and --button1 was given	button1	0
Command file quit closed the window	ok (unchanged)	0
--timeout elapsed	timeout	1
The quit key closed the window	quit	1
Unhandled error	—	1

Only 0 and 1 are ever returned. There is no exit code 2: swiftDialog's convention of 2 for button2 and 4 for a timeout is not implemented, and no --button2 is rendered to press. A script that needs to distinguish "user acknowledged" from "we ran out of time" can use 0 versus 1; a script that needs more than two outcomes has to build them out of several dialogs.

dialog.exe also prints two lines to stdout before exiting, which scripts may parse:

Result: button1
Timestamp: 2026-09-03 10:14:22

Note that stdout is noisy: the current build writes a large number of [DEBUG] lines from the WPF path and [CommandFileMonitor] lines from the watcher. Parse for the Result: prefix rather than assuming a clean stream.

Flags that do not exist

These appear in older README/docs/ snippets and in scripts copied from them. The parser ignores them silently:

Token	Reality
--progressbar	Not a flag. Use --progress
--debug	Not a flag. The build is already verbose on stdout
--jsonfile, --jsonstring	Not implemented; there is no CLI path into the JSON configuration model
--infobox, --infotext, --notification, --textfield, --checkbox, --selecttitle, --webcontent, --position, --moveable, --blurscreen, --ontop, --small/--big	swiftDialog options with no csharpDialog equivalent — see Coming From swiftDialog