Running JIPipe headless/CLI

You can run JIPipe pipelines using a command line interface (CLI) and inside headless environments.

The basic usage of the CLI is as follows:

        ./ImageJ-linux64 --memory 8G --pass-classpath --full-classpath --main-class org.hkijena.jipipe.cli.JIPipeCLIMain [options]
    

You can list the available parameters with

        ./ImageJ-linux64 --memory 8G --pass-classpath --full-classpath --main-class org.hkijena.jipipe.cli.JIPipeCLIMain help
    

JIPipe CLI https://www.jipipe.org/
Developed by Applied Systems Biology, HKI Jena, Germany

run <options>
Runs a project file and writes outputs to the specified directory.
--project <Project file>                                                       Sets the project file to run

Optional parameters:
--output-folder <Output folder>                                                Sets the output directory (if not set, will use a temporary directory)
--num-threads <N=1,2,...>                                                      Sets the maximum number of threads for parallelization
--overwrite-parameters <JSON file>                                             Overrides parameters from a JSON file (key to value pairing)
--P<Node ID>/<Parameter ID> <Parameter Value (JSON)>                           Overrides one parameter from the specified JSON data
--overwrite-user-directories <JSON file>                                       Read user directory overrides from a JSON file (object with key to value pairing)
--U<User directory key> <User directory value>                                 Overrides one user directory key with the specified directory
--output-results <all/none/only-compartment-outputs>                           Determines which standard JIPipe outputs are written (default: all)

Advanced settings:
--verbose                                                                      Print all initialization logs (a lot of text)
--profile-dir                                                                  Sets the directory for the JIPipe profile (location of settings, artifacts, etc.)
--fast-init                                                                    Skips the validation steps to make the JIPipe initialization faster

To run this tool, execute following command:
<ImageJ executable> --debug --pass-classpath --full-classpath --main-class org.hkijena.jipipe.cli.JIPipeCLIMain

Environment variables:
JIPIPE_OVERRIDE_USER_DIR_BASE                                                  Overrides the base directory where JIPipe looks for profiles (the directory itself will contain sub-directories for the JIPipe version)

    

The basic command to run a JIPipe pipeline with default settings is as follows:

./ImageJ-linux64 --memory 8G --pass-classpath --full-classpath --main-class org.hkijena.jipipe.cli.JIPipeCLIMain run --project [your project file] --output-folder [work directory/output folder]

You can use additional CLI arguments to control the behavior of the pipeline execution and override various project and pipeline settings.

Disabling standard JIPipe outputs

By default, the JIPipe CLI will save all results, including intermediate outputs into the output directory in the JIPipe standard format. To control this behavior, use the --output-results parameter.

--output-results all: ⭐ The default option. Save all results, including intermediates to the output directory.
--output-results only-compartment-outputs: Save only the outputs of compartment output nodes.
--output-results none: Do not save any results using JIPipe's standard format.

Overriding parameters

Any node parameter can be overridden prior to executing the pipeline using a parameter file and/or by directly providing parameters via the CLI.

Each parameter has a unique project-wide identifier in the following format:

[node-uuid]/[parameter-id]

The node UUID can be found in the Documentation panel after selecting a node and for example looks like this:

b3655c10-349a-410a-8d26-38f7430f957d

The parameter ID can be displayed by clicking the button next to a parameter in the Parameters panel or by browsing through Right-click node | Explore parameters.

If you use the Documentation panel, there will be an entry Unique identifier

The identifier for the parameter Auto threshold 2D | Method for example might look as following:

7db79633-5589-49cf-9adf-e70abba39076/method

Obtaining valid parameter values

JIPipe stores parameters in JSON format. While most parameters are stored in a straight-forward way (e.g., numbers, booleans, texts, enums, ...), there are some parameter types that require a specific format.

To obtain a valid value, you have two options:

Copying a parameter: Change the parameter in a node, and click the arrow next to the button. Then select Copy to copy the value as JSON.
Using the parameter explorer: Open the parameter explorer with Right-click node | Explore parameters where you can play around with the values.

Using a parameter file

The parameter file must be in JSON format and should contain the parameter values in JSON format assigned to the project-wide parameter identifier.

For example:

            {
                "7db79633-5589-49cf-9adf-e70abba39076/method": "Otsu",
                "7db79633-5589-49cf-9adf-e70abba39076/threshold-annotation": {
                    "content": "Threshold",
                    "enabled": false
                }
            }
        

Provide the file using the --overwrite-parameters [file] setting.

Directly setting parameters

You can also set parameters directly by using the --P[parameter key] [parameter value] setting. For example:

            --P7db79633-5589-49cf-9adf-e70abba39076/method Otsu --P7db79633-5589-49cf-9adf-e70abba39076/threshold-annotation {\"content\":\"Threshold\", \"enabled\":false}
        

Overriding user directories

Similar to parameters, project user directories can also be overridden using file(s) and CLI parameters.

Using a settings file

Provide a JSON file that assigns a new path to the user directory key. For example:

            {
                "input_dir": "PATH TO NEW INPUT DIR",
                "output_dir": "PATH TO NEW OUTPUT DIR"
            }
        

Directly overriding directories

Use the --U[user directory key] [value] setting to set a new path for a user directory using the CLI.

Overriding the profile directory

By default, JIPipe uses a profile directory based on the current home directory of the executing user. You can manually override the directory that contains the profiles using the --profile-dir [profile directory] option.

Setting the number of threads

You can set the number of threads using the --num-threads [number of threads] parameter.

Advanced options

--verbose: If set, print the full JIPipe initialization log. (In older JIPipe versions, this is the default)
--fast-init: If set, skip some checks during the JIPipe initialization, so the tool starts faster.
JIPIPE_OVERRIDE_USER_DIR_BASE (Environment variable): Allows to override where JIPipe builds it's hierarchy of profile directories. Also available for the regular startup (GUI). Overridden by --profile-dir.

Last modified: 20 February 2025