Home

csharpDialog

csharpDialog is a Windows command-line utility that renders an admin-driven, user-facing dialog from CLI flags and keeps updating it while it is on screen, driven by a plain-text command file. It is the Windows counterpart of swiftDialog on macOS, and it exists for the same reason: management-system scripts need a way to tell a signed-in user what is happening and how far along it is, without shipping a bespoke GUI with every script.

The shipped executable is named dialog.exe, which keeps script bodies close to the swiftDialog originals.

A running dialog can show a title, a message, a scrolling list of items each with its own status indicator, a progress bar with a progress caption, and one button. A controlling script appends lines like progress: 60 or listitem: update, title: Chrome, status: success to the command file and the window reacts within about a tenth of a second. When the work is finished the script appends quit and the process exits.

What this port is and is not

csharpDialog covers the subset of swiftDialog that management scripts actually lean on: live progress, a live list, live title/message/button text, a hard-to-dismiss window, and a scriptable exit. It does not implement swiftDialog's form controls (text fields, checkboxes, dropdowns, file pickers), its --jsonstring/--jsonfile input, its --infobox/--infotext chrome, its --webcontent view, or its --notification mode. Coming From swiftDialog maps flag-for-flag what exists, what is renamed, and what is missing.

Several flags are parsed but have no effect in the shipped GUI. That is called out explicitly and per-flag in CLI Reference rather than glossed over — knowing which flags are inert is the difference between a working script and a silent no-op.

Quick start

Install the MSI from the Releases page, then open a new shell so the installer's PATH change is picked up.

dialog --window --title "Hello" --message "csharpDialog is installed."

The --window flag matters. Without one of --window, --fullscreen, --kiosk, --firstrun or --commandfile, dialog.exe falls back to a text-mode prompt on stdout instead of drawing a window. See CLI Reference.

A progress dialog driven from a script is the shape most callers want:

$commandFile = "$env:TEMP\dialog-commands.txt"
Remove-Item $commandFile -Force -ErrorAction SilentlyContinue
$dialog = Start-Process dialog -PassThru -ArgumentList @(
    "--window", "--title", "Installing software",
    "--message", "This will take a few minutes.",
    "--progress", "--commandfile", $commandFile
)
Start-Sleep -Seconds 2
Add-Content $commandFile "listitem: add, title: Chrome, status: wait, statustext: Queued" -Encoding UTF8
Add-Content $commandFile "listitem: update, title: Chrome, status: success, statustext: Installed" -Encoding UTF8
Add-Content $commandFile "progress: 100" -Encoding UTF8
Add-Content $commandFile "quit" -Encoding UTF8

More worked examples, including a locked provisioning window and a live install tracker, are in Recipes.

Contents

Page	What it covers
Installation	Supported Windows versions, MSI / .pkg / zip, PATH, verification, uninstall
CLI Reference	Every flag the argument parser accepts, with type, default, effect and known no-ops; exit codes
Command File Reference	The live-update command language: every verb, its parameters, and how the file is read
Recipes	Realistic scripts: progress dialog, blocking notification, live install list, locked window
Configuration	On-disk paths, registry keys, environment variables and defaults the code reads
Architecture	Projects, front-end selection, the command-file loop, where state lives
Cimian Integration	--cimian / --firstrun / --autolaunch, log tailing, manifest parsing, icon cache
Coming From swiftDialog	Flag-by-flag mapping, behavioural differences, and the gaps
Troubleshooting	Symptom → cause → fix, log locations, session 0, silent no-ops
Development	Repo layout, build, packaging, the CI and release workflows, signing
FAQ	Questions a Windows admin arriving from swiftDialog asks first