RunCommand plugin


Plugin=RunCommand

Executes an external command or program in Windows, allowing the skin to obtain and use any output from the program.

There are several important differences between this and just executing a command with something like:

LeftMouseUpAction=["SomePath\SomeProgram.exe" "SomeParameters"]

  • The command can be run with a hidden initial state, to eliminate the cmd.exe (DOS) Command Prompt window that is created when an external command-line command or program is executed normally from Rainmeter.
  • Any output of the command to STDOUT (the "Standard Out" string output of a program in a cmd.exe Command Prompt window) can be captured, either directly, as the the value of the plugin measure, or piped to a text file for additional processing as needed.
  • The plugin can detect that a command is "finished", and your skin can in effect wait for the command to be done before taking some action and using any returned value.
  • The plugin can detect that a command caused a set of "error" return codes, and the skin can take some action based on success or failure of the command and the type of error.
  • The plugin can be set with a "timeout" value, which will automatically end the external command or program when the timeout value is reached.

Overview

What the plugin does when triggered with [!CommandMeasure MeasureName "Run"] is to execute what is defined in the measure's Program option, appending any program parameters defined in the Parameter option.

In most cases, the purpose of the plugin is to execute a Command Line Interface (CLI) program that takes some action or returns some value. Command-line programs by their nature always run in a cmd.exe Command Prompt window.

The plugin will monitor the program defined in the Program option, and when it ends, when the executable terminates, any string output the program did to STDOUT (Standard Out) will be captured and set as the string value of the plugin measure.

The string value of the measure

The string value of the measure will be any output that the program writes to STDOUT. In effect, what you would see if you manually ran the command in a cmd.exe Command Prompt window will become the string value of the measure.

The number value of the measure

The number value of the measure will indicate if the command finished with or without any errors. You can get the number value of the measure by using Section Variables (e.g. [MeasureName:]). Before the command has first run, the number value of the measure will be -1. While the command is running, the number value of the measure will be 0. If an error occurs, the number value of the measure will indicate the type of error that has occurred. If the program finishes without error, the number value of the measure will be 1, meaning "success". These can be used to take different skin actions depending on the numeric return value.

Options

General measure options

All general measure options are valid.

Program Default: %ComSpec% \U \C

The program to run. If not specified, the default value is the %ComSpec% environment variable (normally cmd.exe) with the parameters "\U" for Unicode pipe output and "\C" to close the Command Prompt window and exit the cmd.exe shell when finished.

Generally it is best to leave this undefined and use the Parameter option to define the command and parameters to be executed. Command-line program will simply cause Windows to first execute cmd.exe anyway, to create the Command Prompt environment the program must run in. Basic "DOS" commands like "dir" or "copy" don't have any .exe "program" to run in any case, and are simply internal functions of cmd.exe.

Information on cmd.exe.

Parameter Default: None

Command-line parameters. If no Program is specified, this option represents the entire command-line, which will be executed in the context of the default cmd.exe Command Prompt window as described above.

Note: Care should be taken to properly "quote" commands with a path or parameters having spaces in values.

Example: Parameter=wmic os get lastbootuptime.

State Default: Hide

Initial "visible state" of the program.

  • Hide (default)
    Attempts to hide the program's window from being visible. This option is not recommended for GUI programs and/or programs that expect any form of input.
  • Show
    Shows the program's normal window.
  • Minimized
    Attempts to start the program minimized.
  • Maximized
    Attempts to start the program maximized.

Notes: If State=Hide, the plugin will automatically "kill" any program it executed, when either the skin is refreshed or unloaded, or Rainmeter is exited.

A few programs with a windowed GUI user-interface (for instance Calc.exe) explicitly show themselves and will not respond to initial state requests like Hidden or Minimized. This will be a rare problem, as normally there is no useful reason to use this plugin to execute GUI programs from the command line. They will likely take no desirable independent action, and will have no STDOUT "output" in any case.

FinishAction Default: None

Bangs or other actions that are executed when the program has finished / exited.

OutputFile Default: None

Optional path and file name where the STDOUT output will be saved. The file's encoding is controlled by the OutputType option. The default path will be the skin folder.

OutputType Default: UTF-16

Type of output to be expected from the program. Any OutputFile will also be encoded with these values. You must be sure that what you tell it here matches what is actually output by the program you run. This option does not "control" what is output by the program.

  • UTF-16 (default)
  • UTF-8
  • ANSI

Note: Although by default cmd.exe will be executed with the \U (UTF-16 Unicode) parameter, that does not mean that any program executed in the Command Prompt window will necessarily produce output in UTF-16. While most internal Windows commands like "dir" will produce UTF-16 output, a great many command-line programs will produce ANSI output. If you get gibberish characters returned by the measure, setting OutputType=ANSI will often correct the issue.

StartInFolder Default: Skin folder

Optional path which will be used as the "Start in" folder for the executed program. The default path will be the skin folder.

Timeout Default: -1

Timeout value in milliseconds. If positive, RunCommand will either "Close" the program if the State is other than Hide or "Kill" the program if the State is Hide. The default is -1, which means no timeout. Any FinishAction will run even if the program does not actually terminate (e.g. if closing "Notepad" and clicking "Cancel" when asked to save the document). It should be noted that this value is independent of any Update or UpdateDivider values in the skin.

Note: Because Rainmeter strips any quotes from the start and end of an option if both exist, it is important to double double-quote the Program and Parameter options If the overall command or parameter requires both starting and ending quotes.

Example: Program=""C:\Program Files\Some Program\Something with a space.exe""

Plugin Commands

Run

Runs the program. The plugin will take no action unless triggered with this command.

Example: LeftMouseUpAction=[!CommandMeasure MeasureName "Run"]

Close

Sends a normal "close" message to the program.

The program may produce an "are you sure?" prompt before closing. Some programs can cancel the closing of the program, in which case the plugin will continue to gather any output.

Example: LeftMouseUpAction=[!CommandMeasure MeasureName "Close"]

Kill

Terminates the program without notice. This should generally be used when ending a program that was run with State=Hide.

Example: LeftMouseUpAction=[!CommandMeasure MeasureName "Kill"]

Error codes

Here is a list of possible error codes returned by the plugin:

  • 100 Unknown command. This happens when an invalid !CommandMeasure command was sent to the plugin.
  • 101 Program still running. This happens when trying to Run the program again before it has finished running.
  • 102 Program not running. This happens when trying to Close or Kill a program that is not running.
  • 103 Cannot start program. This happens when the Program option is invalid. Usually a wrong path or typo in the Program option is the cause. Note that cmd.exe may start perfectly well but be unable to execute a command or program passed as a Parameter option. That will not trigger this error code.
  • 104 Cannot save file. This happens when there is an error saving the file. This could happen if writing to a locked location or file. The string value of the plugin will still contain any output of the program.
  • 105 Cannot terminate process. There was an error when attempting to close or kill the program. This should rarely happen. If so, it might be necessary to open the Windows Task Manager and manually close the program.
  • 106 Cannot create pipe. This happens when the plugin cannot create a pipe to the program trying to run. The program will not run if this error happens. This error should rarely happen.

Note: These error codes are produced by the plugin, and have nothing to do with any error encountered by the executed program itself. Errors from the program will generally be displayed in the STDOUT output, and can be tested for and reacted to there.

Example

[Rainmeter]
Update=1000
DynamicWindowSize=1
AccurateText=1
[MeasureRun]
Measure=Plugin
Plugin=RunCommand
Parameter=wmic cpu get Name
State=Hide
OutputType=ANSI
OutputFile=#CURRENTPATH#CPUName.txt
RegExpSubstitute=1
Substitute="Name.*#CRLF#":"","#CRLF#":""
[MeterRun]
Meter=String
FontSize=11
FontColor=255,255,255,255
SolidColor=47,47,47,255
Padding=5,5,5,5
AntiAlias=1
Text=Click to Run
LeftMouseUpAction=[!CommandMeasure MeasureRun "Run"]
[MeterResult]
Meter=String
MeasureName=MeasureRun
Y=10R
FontSize=14
FontColor=255,255,255,255
AntiAlias=1

This example will run the program wmic.exe, which is in the Windows %PATH% and thus needs no path on the command itself.

The wmic.exe program will use the parameters of "cpu get Name". The program will be run in a "hidden" cmd.exe Command Prompt window, and nothing visible will happen.

In effect this is really executing "%windir%\system32\cmd.exe \U \C" "wmic cpu get Name".

The output of the wmic.exe program (the "name" of your CPU in this case) will be written to STDOUT in the hidden cmd.exe Command Prompt window, which will be captured by the plugin and set as the string value of the [MeasureRun] measure.

The Substitute option is being used to strip off some extra label information and linefeeds that are output by the program.

Additionally, the file defined in OutputFile will contain the entire output of the wmic command, which in this example might be:

Name
Intel Core i7 920 @ 3.20GHz

Additional parsing of this file could be done with the WebParser plugin or String measures if you wanted for instance to obtain multiple separate values from the single command output.