Command line interface

JIPipe projects can be run from within a command line interface (CLI).

To run a project with the CLI and output its result to the specified directory, run

./ImageJ --pass-classpath --full-classpath --main-class org.hkijena.jipipe.JIPipeCLI run --project <project file> --output-folder <output folder>

Replace ImageJ with the appropriate ImageJ executable for your operating system.

Command line options

You can always display a list of available options by running

./ImageJ --pass-classpath --full-classpath --main-class org.hkijena.jipipe.JIPipeCLI help

The following options are available for the run command

./ImageJ --pass-classpath --full-classpath --main-class org.hkijena.jipipe.JIPipeCLI run <options>

Option	Description
--project <project file>	Mandatory option that determines which project should be run.
--output-folder <directory>	Mandatory option that sets the output directory. If the folder does not exist, JIPipe will create it. The content of the directory are in the standard JIPipe output format.
--num-threads <threads>	Sets the number of threads (default 1). If you have issues with thread counts larger than 1, please notify us.
--override-parameters <JSON file>	Overrides parameters in the project file from a JSON document.
--P<Node ID>/<Parameter ID> <Parameter value>	Overrides a specific parameter in the project from CLI. Overwrites entries from --override-parameters
--output-results <all/none/only-compartment-outputs>	Determines which results are written into the output directory: all (default) writes all outputs none writes no outputs are written only-compartment-outputs writes only outputs of compartments, but no intermediate results

Overwriting parameters

The CLI can overwrite parameters before the project is run. Parameter values are provided in JSON format that can be obtained by copying a parameter or by using the parameter explorer feature.

Obtaining valid parameter values

The most simple way to obtain a valid parameter JSON is to copy an existing parameter via the parameter UI. To do this, click the ⏷ button next to the parameter help. Then select “Copy”.

Alternatively, right-click the node of interest and select “Explore parameters”. In the window you can freely change a parameter of the same type in the “Value tester” and obtain a valid JSON in real time.

Obtaining the parameter global unique identifier

To target a parameter in the project, you must obtain its global unique identifier. To to this, click the 🯄 button next to the parameter of interest and find the “Global parameter identifier” value in the help.

Overwriting parameters via a JSON file

You can provide a JSON file that maps the global parameter identifier to the parameter JSON value.

For example:

{
    "ebf861d1-a4d4-47a4-85b1-42c3ab468ad4/method": "Default",
    "ebf861d1-a4d4-47a4-85b1-42c3ab468ad4/threshold-annotation": {"content":"Threshold","enabled":true}
}

Overwriting parameters via CLI options

You can also overwrite parameters via the –P CLI options. This mode can be combined with the JSON file. Parameters overwritten with the –P flag overwrite settings made in the JSON file.

./ImageJ --pass-classpath --full-classpath --main-class org.hkijena.jipipe.JIPipeCLI run --Pebf861d1-a4d4-47a4-85b1-42c3ab468ad4/method \"Default\" <options>

Running on headless Linux servers / avoiding windows

The CLI command presented so far are not suitable for running JIPipe in a headless environment (e.g., Linux servers, Docker containers, …). While ImageJ provides a –headless option, the program might crash due to the dependency on GUI components of some data types (e.g., ROI).

On Linux, you can install xvfb and wrap the ImageJ command into xvfb-run:

xvfb-run -a ./ImageJ --pass-classpath --full-classpath --main-class org.hkijena.jipipe.JIPipeCLI run <options>

We recommend to use xvfb-run with the -a option to automatically find a free XServer port.