search

Hop Run

hashtag
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.

hashtag
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

Usage: <main class> [-ho] [-e=<environmentOption>] [-f=<filename>]
                    [-j=<projectOption>] [-l=<level>]
                    [-r=<runConfigurationName>] [-ps=<parametersSeparator] [-p=<parameters>[,
                    <parameters>...]]... [-s=<systemProperties>[,
                    <systemProperties>...]]...
  -a, --startaction=<startActionName>
                          The name of the action where to start a workflow
  -e, --environment=<environmentOption>
                          The name of the lifecycle environment to use
  -f, --file=<filename>   The filename of the workflow or pipeline to run
  -h, --help              Displays this help message and quits
  -j, --project=<projectOption>
                          The name of the project to use
  -l, --level=<level>     The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL
  -l, --level=<level>     The debug level, one of NOTHING, ERROR, MINIMAL, BASIC, DETAILED, DEBUG, ROWLEVEL
  -lf, --logfile=<logfile-name> The complete filename where hop-run will write the Hop console log
  -m, --metadata-export=<metadataExportFile>
                          A file containing exported metadata in JSON format
  -o, --printoptions      Print the used options
  -p, --parameters=<parameters>[,<parameters>...]
                          A list of PARAMETER=VALUE pairs
  -ps, --parameters-separator=<parametersSeparator>
                          A character to be used as separator for our list of PARAMETER=VALUE pairs (default is ",").
  -r, --runconfig=<runConfigurationName>
                          The name of the Run Configuration to use
  -s, --system-properties=<systemProperties>[,<systemProperties>...]
                          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 environmentsarrow-up-right 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 Confarrow-up-right

-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 configurationsarrow-up-right for more details.

-s

--system-properties

A comma separated list of KEY=VALUE pairs

hashtag
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.

hashtag
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:

    Your output will be similar to what is shown below:

  • Linux, macOS

    Open a terminal, change to the directory where you unzipped Apache Hop and run:

    Your output will be similar to what is shown below:

hashtag
Parameter Examples

This is a list of examples on how the parameters on this command are parsed

Normal Usage

Result:

Key
value

key1

value1

key2

value2

Spaces in value Usage

Result:

Key
value

key1

This value contains spaces

key2

value2

Commas in value Usage

Result:

Key
value

key1

value1,value2

Forcing quotes in value

Result:

Key
value

key1

"String with spaces"

Last updated 2025-09-04 18:20:50 +0200

Last updated