CMDGUI User Manual

Introduction

cmdgui is a tool that creates graphical interfaces for command-line programs. The goal to be able to turn the /h output of most commands into a GUI, with minimal extra markup. I love the command line for frequently repeated tasks where I've memorized the options. But for commands I don't use too often I'm stuck looking up /h first, taking away much of the speed advantage of the command line. At that point it's quicker to use it directly as a GUI with point and click. That's the niche this tool fills.

Quick Start

Run cmdgui by passing it a .gui file, via drag and drop, or by associating the .gui scripts with it.

Every .gui file has three parts:

Line 1: The command name (e.g., PING, ROBOCOPY)
Line 2: A description of what the command does
Line 3+: Markup describing the command's options

Here's the simplest possible example:

PING
Send network test packets to a host
{{required text}} Target hostname or IP address

This creates a dialog with one text field labeled "Target hostname or IP address" and a Run button that executes PING <whatever-you-type>.

Basic File Structure

Command Name (Line 1)

The executable name that will be run. This can be a built-in CMD or Powershell command, a program in your PATH, or a full path to an executable.

Description (Line 2)

A short description displayed at the top of the dialog. Appears in a gray box below the title bar.

Markup (Line 3+)

Lines describing the command's options and arguments. The order in the file is the order arguments appear on the command line.

Example Structure

ROBOCOPY
Copy files and directories with advanced options
{{required dir}} Source directory
{{required dir}} Destination directory
-e  Copy subdirectories including empty ones
-z  Copy files in restartable mode

{{required dir}} is a tag that produces a browse button and warns you before trying to run the command if nothing has been entered. {{dir}} would work the same, but sans warning.

This generates: ROBOCOPY <source> <destination> [-e] [-z]

Markup Reference

Simple Flags (Checkboxes)

Lines that aren't tagged with {{...}} syntax become checkbox flags in the GUI.

-v  Verbose output
/Q  Quiet mode
-r  Recursive processing

Note that a flag can be anything, ending in a space. if you check the box, it gets added to the command line.

Multi-word or non-standard flags (use quotes):

'/setactive 381b4222-f694-41f0-9685-ff5bb260df2e'  Balanced power scheme
"WORD" Label for a flag that is just a word

Flags with Values

Create an input field.

-n {{number}} Number of retries
-w {{text}} Wait time in seconds
-o {{file}} Output file path
-d {{dir}} Working directory

Example: A checkbox labeled "Number of retries" with a text field next to it. If you enter anything into the field, it adds: -n <text>

Available types:

text - Any text input (no validation)
number - Numeric input (no automatic validation)
file - Existing file (validates file exists, adds Browse button)
newfile - New file path (warns if exists, adds Browse button)
dir - Existing directory (validates exists, adds Browse button)
newdir - New directory path (warns if exists, adds Browse button)
filedir - Existing file OR directory (validates exists, adds Browse button)
newfiledir - New file OR directory path (warns if exists, adds Browse button)
drive - Logical drive selection (creates a dropdown of available drives)

Required Fields

Mark arguments that must be provided. These appear at the top of the dialog in a "Required" group box:

{{required text}} Target hostname
{{required file}} Input file to process
{{required filedir}} Source path

Example: A labeled text field (or Browse button for file types) that must be filled in before the command can run.

Required fields use the same types as flags with values (text, number, file, dir, etc.).

Radio Buttons (Mutually Exclusive Options)

Group options where only one can be selected at a time:

{{radiostart}}
/D  Create a directory symbolic link
/H  Create a hard link instead
/J  Create a directory junction
{{radioend}}

This produces three radio buttons in a group. Selecting one deselects the others. Only the selected option's flag is added to the command line. If you don't select any of them, nothing gets added.

If you have to choose one of the radio options, do this {{required radiostart}}, eg

{{required radiostart}}
/c copy file
/m move file
{{radioend}}

The user will have to select /c or /m. No need to tag each line or the radio end.

Empty flags example:

{{radiostart}}
''  Medium verbosity
/v  Verbose
/q  Quiet
{{radioend}}

Selecting "Medium" will add nothing to the command line, but will still be a selectable option in the GUI. Empty flags are useful in radio groups where one option represents "no argument".

You can have multiple radio groups in one file. Each {{radiostart}}...{{radioend}} pair creates a separate group.

Complete Examples

MKLINK - Create Symbolic Links

cmd /c MKLINK
Create a symbolic link or junction
{{radiostart}}
/D  Create a directory symbolic link
/H  Create a hard link instead
/J  Create a Directory Junction
{{radioend}}
{{required newfiledir}} Link name
{{required filedir}} Target path

Generates: MKLINK [/D or /H or /J] <link> <target>

PING - Network Connectivity Test

PING
Send ICMP echo requests to test network connectivity
{{required text}} Target hostname or IP address
-t  Ping continuously until stopped
-a  Resolve addresses to hostnames
-n {{number}} Number of echo requests to send
-l {{number}} Send buffer size in bytes
-w {{number}} Timeout in milliseconds
-4  Force using IPv4
-6  Force using IPv6

Generates: PING <target> [-t] [-a] [-n <value>] [-l <value>] [-w <value>] [-4] [-6]

TASKKILL - Terminate Processes

TASKKILL
Terminate one or more processes
{{required radiostart}}
/PID {{number}}  Process ID to terminate
/IM {{text}}  Image name (e.g., notepad.exe)
{{radioend}}
/F  Force termination
/T  Terminate child processes too

Generates: TASKKILL [/PID <value> or /IM <value>] [/F] [/T]

Advanced markup options

That's enough to make most simple command line programs easily controlled by a GUI. But we can go further to make slightly fancier GUIs with the next two tags.

Action Buttons

Create buttons that immediately execute the command with a specific flag:

Powercfg
Switch current power configuration
{{button /setactive 381b4222-f694-41f0-9685-ff5bb260df2e}} Balanced
{{button /setactive 8c5e7fda-e8bf-4a96-9a85-a6e23a8c635c}} High Performance

Syntax: {{button flag}} Description

Example: A button labeled "Balanced". Clicking it adds /setactive 381b4222-f694-41f0-9685-ff5bb260df2e to the command line (plus any other options checked) and immediately executes the command.

Behavior:

When any action buttons are present, the default Run button is hidden
Each button acts like: temporarily add this flag + validate + execute
All validation still applies (required fields must be filled)
Button text is the description after }}
The flag inside {{button ...}} can include spaces without needing quotes

Use cases:

Quick actions with predefined parameters (power schemes, preset configurations)
Commands where the primary action varies (taskkill with different PIDs)
Wizards where different buttons lead to different command variations

Dynamic GUI Generation ({{batch gui}})

Sometimes you can't hard code the options. For example powercfg requires you use a random sequence of numbers instead of a user-friendly power profile name. But you can use the power of cmd.exe batch files to make a .gui file dynamically and then run that.

Use the {{batch gui}} tag at the very top of your file. Everything after it is executed as a batch script, and any text printed becomes the .gui script that is rendered in the dialog.

{{batch gui}}
@echo off
echo TASKKILL
echo Select task to kill
echo {{radiostart}}
for /f "tokens=1,2" %%a in ('tasklist /NH') do (
    echo /PID %%b /F  %%a
)
echo {{radioend}}

How it works:

Everything after {{batch gui}} is executed as a batch script
The script's output is captured
The output is parsed as if it were a .gui file
The temporary batch file is deleted

Embedded Batch Commands ({{batch cmd}})

The {{batch cmd}} tag allows you to embed a batch script that is executed when the user clicks "Run". This is useful when you want the GUI to collect parameters and then pass them to a script instead of a single executable.

Place {{batch cmd}} anywhere in your markup section. Everything after it until the end of the file is the script.

MYCOMMAND
Custom script execution
{{required text}} Name
{{batch cmd}}
@echo off
echo Hello %1, welcome to the script!
pause

Behavior:

The GUI is built normally based on the markup before {{batch cmd}}.
When "Run" is clicked, all selected GUI arguments are passed as command-line parameters to the embedded script.

Dynamic TASKKILL - Kill Running Processes

This example also includes buttons, for a single click option to forcibly close a program.

{{batch gui}}
@echo off
echo TASKKILL
echo Select a running process to kill
setlocal enabledelayedexpansion
for /f "skip=3 tokens=1,2" %%a in ('tasklist') do (
    if not "%%b"=="" (
        echo {{button /F /PID %%b}}  %%a (PID: %%b)
    )
)
endlocal

Generates: A button for each running process. Clicking a button executes taskkill /F /PID <that-process-id>.

Tips & Best Practices

File Order = Command Line Order

The order of options in your .gui file is the order they appear on the command line. Put positional arguments in the right order.

Required Fields Appear at Top

Required fields are always displayed at the top of the dialog, even if they appear later in your .gui file. The command line still uses file order.

Browse Buttons Are Automatic

Any field with type file, dir, filedir, etc. automatically gets a Browse button. No extra markup needed.

Multi-Word Flags Need Quotes

If a flag contains spaces, wrap it in quotes:

'/setactive 381b4222-f694-41f0-9685-ff5bb260df2e'  Balanced power scheme

Version: 1.1
Last Updated: February 2026

Recent Changes:

Fixed path validation for root drives and trailing slashes
Added adaptive throttling for console output (28ms normal, 100ms when heavy)
Smart auto-scroll respects user scroll position
Fixed Escape key behavior when process is not running