# Hop Run ## Hop Run Hop Run is a command line tool to run your workflows and pipelines. Hop Run can be launched through the script with the corresponding name in your Hop installation directory, either `hop-run.sh` on Mac and Linux or `hop-run.bat` on Windows. Except for the laucher script, all options are platform agnostic; there is no difference in the way hop-run works on any operating system. ### Hop Run Options You can display Hop Run’s options by running the command without any options. On Windows, run `hop-run.bat`. The command on Mac and Linux is `hop-run.sh`. You’ll see the option listed in a similar output to the one below: Usage Output of help ```highlight Usage:
[-ho] [-e=] [-f=] [-j=] [-l=] [-r=] [-ps=[, ...]]... [-s=[, ...]]... -a, --startaction= The name of the action where to start a workflow -e, --environment= The name of the lifecycle environment to use -f, --file= The filename of the workflow or pipeline to run -h, --help Displays this help message and quits -j, --project= The name of the project to use -l, --level= The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL -l, --level= The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL -lf, --logfile= The complete filename where hop-run will write the Hop console log -m, --metadata-export= A file containing exported metadata in JSON format -o, --printoptions Print the used options -p, --parameters=[,...] A list of PARAMETER=VALUE pairs -ps, --parameters-separator= A character to be used as separator for our list of PARAMETER=VALUE pairs (default is ","). -r, --runconfig= The name of the Run Configuration to use -s, --system-properties=[,...] A comma separated list of KEY=VALUE pairs -v, --version Print version information and exit ``` The available options are listed in more detail in the table below: | Short | Extended | Description | | ----- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-e` | `--environment` |

The name of the environment to use.

Check the documentation on environments for more details.

| | `-a` | `--startaction` | The name of the action where to start a workflow | | `-f` | `--file` | The filename of the workflow or pipeline to run | | `-h` | `--help` | Displays this help message and quits. | | `-j` | `--project` | The name of the project to use when running a pipeline or workflow | | `-l` | `--level` | The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL | | `-lf` | `--logfile` | The complete filename where hop-run will write the Hop console log | | `-m` | `--metadata-export` | A file containing exported metadata in JSON format. See also the metadata export option in [Hop Conf](https://github.com/mbertazz/hop-docs-md/blob/main/modules/ROOT/pages/hop-run/hop-tools/hop-conf/hop-conf.VKNjxFg0LY) | | `-o` | `--printoptions` | Print the used options | | `-p` | `--parameters` | A comma separated list of PARAMETER=VALUE pairs | | `-ps` | `--parameters-separator` | A character to be used as separator for our list of PARAMETER=VALUE pairs (default is ","). | | `-r` | `--runconfig` | The name of the Run Configuration to use. Check the [documentation on run configurations](https://github.com/mbertazz/hop-docs-md/blob/main/modules/ROOT/pages/hop-run/pipeline/pipeline-run-configurations/pipeline-run-configurations.VKNjxFg0LY) for more details. | | `-s` | `--system-properties` | A comma separated list of KEY=VALUE pairs | ### Possible exit codes Hop Run currently finishes with one of four exit codes. In all cases except `0`, check the error logs for more detailed information for your specific error. | Exit code | Error Message | Description | | --------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | 0 | None | No error message. Everything worked flawlessly. | | 1 | Error found during execution! | There was an error executing the workflow or pipeline. | | 2 | General error found, something went horribly wrong! | There was a general error that caused Hop Run to fail completely. | | 9 | None | There was an error parsing the provided parameter information. Hop Run shows the syntax summary and exists. | ### Examples The example below runs the `switch-case-basic.hpl` pipeline from the samples project through `hop-run`.\ * Windows Open a command (CMD) window, change to the directory where you unzipped Apache Hop and run: ``` hop-run.bat -j samples -r local -f ${PROJECT_HOME}/transforms/switch-case-basic.hpl ``` Your output will be similar to what is shown below: ``` "C:\Program Files\Microsoft\jdk-11.0.17.8-hotspot\\bin\java" -classpath lib\core\*;lib\beam\*;lib\swt\win64\* -Djava.library.path=lib\core;lib\beam "-Xmx2048m" -DHOP_AUDIT_FOLDER=.\audit -DHOP_PLATFORM_OS=Windows -DHOP_PLATFORM_RUNTIME=Run -DHOP_AUTO_CREATE_CONFIG=Y org.apache.hop.run.HopRun -j samples -r local -f ${PROJECT_HOME}/transforms/switch-case-basic.hpl ===[Starting HopRun]========================================================= 2022/12/12 14:09:58 - HopRun - Enabling project 'samples' 2022/12/12 14:09:58 - HopRun - Starting pipeline: config/projects/samples/transforms/switch-case-basic.hpl 2022/12/12 14:09:58 - switch-case-basic - Executing this pipeline using the Local Pipeline Engine with run configuration 'local' 2022/12/12 14:09:58 - switch-case-basic - Execution started for pipeline [switch-case-basic] 2022/12/12 14:09:58 - Test Data.0 - Finished processing (I=0, O=0, R=0, W=5, U=0, E=0) 2022/12/12 14:09:58 - Switch id.0 - Finished processing (I=0, O=0, R=5, W=5, U=0, E=0) 2022/12/12 14:09:58 - Output 2.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:09:58 - Output default.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:09:58 - Output 1.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:09:58 - Output 4.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:09:58 - Output 3.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:09:58 - switch-case-basic - Pipeline duration : 0.542 seconds [ 0.542" ] ``` * Linux, macOS Open a terminal, change to the directory where you unzipped Apache Hop and run: ``` ./hop-run.sh -j samples -r local -f ${PROJECT_HOME}/transforms/switch-case-basic.hpl ``` Your output will be similar to what is shown below: ``` 2022/12/12 14:06:39 - HopRun - Enabling project 'samples' 2022/12/12 14:06:39 - HopRun - Relative path filename specified: config/projects/samples//transforms/switch-case-basic.hpl 2022/12/12 14:06:39 - HopRun - Starting pipeline: config/projects/samples//transforms/switch-case-basic.hpl 2022/12/12 14:06:39 - switch-case-basic - Executing this pipeline using the Local Pipeline Engine with run configuration 'local' 2022/12/12 14:06:39 - switch-case-basic - Execution started for pipeline [switch-case-basic] 2022/12/12 14:06:39 - Test Data.0 - Finished processing (I=0, O=0, R=0, W=5, U=0, E=0) 2022/12/12 14:06:39 - Switch id.0 - Finished processing (I=0, O=0, R=5, W=5, U=0, E=0) 2022/12/12 14:06:39 - Output 2.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:06:39 - Output default.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:06:39 - Output 4.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:06:39 - Output 3.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:06:39 - Output 1.0 - Finished processing (I=0, O=0, R=1, W=1, U=0, E=0) 2022/12/12 14:06:39 - switch-case-basic - Pipeline duration : 0.499 seconds [ 0.499" ] ``` #### Parameter Examples This is a list of examples on how the parameters on this command are parsed **Normal Usage** ``` --parameters=key1=value1,key2=value2 ``` Result: | Key | value | | ---- | ------ | | key1 | value1 | | key2 | value2 | **Spaces in value Usage** ``` --parameters=key1="This value contains spaces",key2=value2 ``` Result: | Key | value | | ---- | -------------------------- | | key1 | This value contains spaces | | key2 | value2 | **Commas in value Usage** ``` --parameters=key1=\"value1,value2\" ``` Result: | Key | value | | ---- | ------------- | | key1 | value1,value2 | **Forcing quotes in value** ``` --parameters=key1="\"\"String with spaces\"\"" ``` Result: | Key | value | | ---- | -------------------- | | key1 | "String with spaces" | Last updated 2025-09-04 18:20:50 +0200 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.primeur.com/data-shaper-1.21/index-2/index.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.