Running RiverWare in Batch Mode
The RiverWare Command Language (RCL) facility allows models to be run in batch mode. While in this mode, RiverWare does not open a user interface, but instead runs in background mode.
In batch mode, the user provides RiverWare with a script file, which contains the commands RiverWare executes. Commands are entered through the RCL file, rather than through the user interface. The commands are described in detail in the following sections.
The syntax to invoke RiverWare in batch mode from a command prompt is:
RiverWare.exe --batch <script file>
The following example will invoke the batch script file called BasinOperationsScript.rcl and will write the diagnostics output to file called BasinOperationsDiagnostics.txt.
RiverWare.exe --batch “C:\MyRiverWareFiles\BasinOperationsScript.rcl” --log “C:\MyOutputs\BasinOperationsDiagnostics.txt”
The <script file> defines how the batch run should proceed. In the file, you specify commands to open a model, load a ruleset if necessary, start a run, and save the results. In the simplest case, you will open a model, run a simulation, save the model, and exit batch mode. The following RCL commands support these actions (“#” indicates a comment in RCL, a line that is not executed):
# Open the model
OpenWorkspace <Model Name>
# Run the simulation
StartController
# Save the model
SaveWorkspace <Model Name>.saved.mdl
# Close the opened model and exit RiverWare
CloseWorkspace
This is a very simple example. The full complement of key words and commands is presented in the following sections.
Safe-Tcl and expandedTcl
The RiverWare Command Language is built on top of the Tool Command Language (Tcl). RCL batch scripts can make use of general Tcl commands to extend the functionality by adding elements such as conditional logic, iterative looping, and so on. Use of general Tcl commands in RCL scripts is not covered here. An online search for “Tcl” can provide documentation of Tcl commands.
By default, RiverWare uses “Safe-Tcl.” Safe-Tcl prohibits the use of commands that can make changes to the file system, run an executable, or could otherwise introduce a security vulnerability if the script file were maliciously modified. Specifically, Safe-Tcl prohibits the use of the following Tcl commands.
cd | file | pwd |
exec | glob | socket |
exit | load | source |
fconfigure | open | vwait |
In order to make use of all Tcl commands including those listed above in a RCL script, the expandedTcl argument can be added to the command line when running RiverWare in batch mode.
Warning: If the expandedTcl option is used, it is the responsibility of the user to make sure the corresponding RCL script is maintained in a secure environment in order to prevent the opportunity for any malicious code to be inserted into the script. When running in the default Safe-Tcl mode, any commands that could potentially introduce malicious behavior will be prohibited from executing.
The command line for a RCL batch script execution using the expandedTcl option would look like the following; note the addition of the --expandedTcl argument at the end.
RiverWare.exe --batch “C:\MyRiverWareFiles\BasinOperationsScript.rcl” --log “C:\MyOutputs\BasinOperationsDiagnostics.txt” --expandedTcl
Revised: 05/30/2026