{"data":{"markdownRemark":{"html":"

The CLI (command line interface) Runner allows users to run models for a specified duration with specified inputs from the command line. This could be useful for users who wish to run the model but do not need to run the server or view the output on the console.

\n

Preparing the model

\n

To run a Model using the CLI, you first need to update your Main.java class so that it runs the server with the array of String arguments passed from the java main method. This allows you to pass your CLI parameters to the Simudyne SDK so the model can be run with your CLI parameters.

\n

Main.Java

\n
public class Main {\n  public static void main(String[] args) {\n    Server.register(\"My Model\", MyModel.class);\n    // Pass args as parameter to Server.run\n    Server.run(args);\n  }\n}
\n

You then need to package, you will need to build a fat jar which will carry your model, the Simudyne SDK and all the necessary dependencies. In this example, we will use the maven-shade-plugin to build this fat jar.

\n
\n

Choosing the maven fat jar plugin

\nThe Simudyne SDK uses Akka HTTP to start the server, whose configuration approach requires all configuration files to be merged when creating fat jars. This is why the `maven-shade-plugin` is used over the `maven-assembly-plugin`. The `maven-shade-plugin` allows us to easily merge all reference.confs (Akka configuration files) on the build classpath so that Akka will use the correct configuration specified in the Simudyne SDK and additional configuration if overriden by the user.\n
\n

To do this, add the following code to the plugins section in the pom.xml file.

\n

pom.xml

\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<project ...>\n    ... properties and dependencies ...\n    <build>\n        <plugins>\n            ... other plugins ...\n            <plugin>\n                <artifactId>maven-shade-plugin</artifactId>\n                <version>3.1.0</version>\n                <configuration>\n                    <transformers>\n                        <transformer implementation=\"org.apache.maven.plugins.shade.resource.AppendingTransformer\">\n                            <resource>reference.conf</resource>\n                        </transformer>\n                        <transformer\n                                implementation=\"org.apache.maven.plugins.shade.resource.ManifestResourceTransformer\">\n                            <mainClass>Main</mainClass>\n                        </transformer>\n                    </transformers>\n                </configuration>\n                <executions>\n                    <execution>\n                        <phase>package</phase>\n                        <goals>\n                            <goal>shade</goal>\n                        </goals>\n                    </execution>\n                </executions>\n            </plugin>\n        </plugins>\n    </build>\n</project>
\n

You can then run the maven command to create the fatJar:

\n

Maven

\n
mvn -s settings.xml clean compile package
\n

Maven will create the jar and place it in the target directory (unless you have specified otherwise in your pom settings). Unless you have given it a specific name, the generated jar will be named <some-artifact-id>-<some-version>-jar.

\n

Running the model

\n

The CLI runner can be used to run any model that has been registerd using Server.register("name", model). It is run by running the generated jar with arguments specifying which model to run and how to run the model.

\n\n

Running the CLI help option

\n
java -jar target/sample-artifact-1.1.0.jar --help
\n

Expected output

\n
Usage: <main class> [options]\n  Options:\n    --model-class\n      Full canonical class name to run.\n...
\n

Required parameters

\n\n

Example:

\n

Model Registration

\n
    Server.register(\"Mortgage Tutorial\", org.example.models.MortgageModel.class);
\n

Running the model

\n
# Running using the registered model name\njava -jar target/simudyne-maven-java-2.1.0-SNAPSHOT.jar --model-name \"Morgage Tutorial\" ...Additional parameters...\n\n# Running using the model class\njava -jar target/simudyne-maven-java-2.1.0-SNAPSHOT.jar --model-class \"org.example.models.MortgageModel.class\" ...Additional parameters...
\n\n

JSON input files

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ParameterTypeRequiredDescription
runsintegerNumber of times to run this scenario. If this is not specified, the scenario will not run.
seeds[long]A list of seeds to set for the runs of this simulation.
scenarioDataobjecttrueKey value pairs of ticks to the inputs to set for those ticks
\n

ExampleInput.json

\n
{\n  \"runs\": 23,\n  \"seeds\": [123,234], // 123 and 234 will be used as the seeds for the first two runs\n  \"scenarioData\": {\n    \"2\": {\n      \"nbHouseholds\": 50 // nbHouseholds will be set to 50 at the second tick\n    },\n    \"100\" : {} // run 100 ticks (without setting any inputs after the second tick)\n  }\n}
\n

CSV input files

\n

CSV input files can only be used to run single runs. The first column in the csv can be used to specify ticks, and the subsequent columns are input fields, so the values in those columns are the values to set for input fields at specific ticks.

\n

ExampleInput.csv

\n
tick,nbHouseholds\n1,200 // nbHouseholds will be set to 200 at the first tick\n2,250 // nbHouseholds will be set to 250 at the second tick\n100 // run 100 ticks (without setting any inputs after the second tick)
\n

Optional parameters

\n","headings":[{"value":"Preparing the model","depth":2},{"value":"Running the model","depth":2},{"value":"Required parameters","depth":3},{"value":"JSON input files","depth":4},{"value":"CSV input files","depth":4},{"value":"Optional parameters","depth":3}],"frontmatter":{"title":"CLI Model Runner","toc":null,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.4/reference/run_mode/cli_run.md","versioned":true,"version":"2.4","kind":"reference","pagePath":"/reference/run_mode/cli_run","chronology":{"prev":{"name":"Multirun Output","path":"/reference/run_mode/multirun_output"},"next":{"name":"Test Kit","path":"/reference/test_kit"}},"lastUpdated":"2026-04-21T13:56:54.853Z"}}