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.
- Hide (default)
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:UTF16
-
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.- UTF16 (default)
- UTF8
- 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 thanHide
or "Kill" the program if theState
isHide
. The default is -1, which means no timeout. AnyFinishAction
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 anyUpdate
orUpdateDivider
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] |
This example will run the program powershell.exe, which is in the Windows %PATH% and thus needs no path on the command itself.
PowerShell will use the parameter of "(Get-CimInstance -ClassName Win32_Processor -Property Name).Name". The program will be run in a "hidden" PowerShell Command Prompt window, and nothing visible will happen.
The output of the PowerShell program (the "name" of your CPU in this case) will be written to STDOUT in the hidden PowerShell 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 trailing spaces and a linefeed in the output.
Additionally, the file defined in OutputFile will contain the entire output of the command, which in this example might be:
Name |
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.