Skip to end of metadata
Go to start of metadata

The Flux command line interface can be used from a shell, command prompt, or script to:

  • Create a Flux engine
  • Start an engine
  • Stop / dispose an engine
  • Check the status of an engine
  • Start, stop, and dispose Flux Agents
  • Check the status of your workflows
  • Add new workflows to the engine
  • Interact with workflows or namespaces that are running on the engine

Using the command-line interface allows you to interact with Flux directly, scheduling and administering workflow files with no programming required.

Displaying the Flux Version

You can use the following command to display your Flux version:

 

After running the command, the Flux version will be displayed to standard output.

Obtaining Help

To get help with the command, run the following command:

This command displays a list of available commands. For help on a specific command, run:

where <command> is the name of a command you'd like more information on. The supported commands are:

CommandDescription
clientRuns a command on an existing Flux engine.
serverAdminister (create, start, or stop) a Flux engine.
agent-clientRuns a command on an existing Flux agent.
agent-serverCreates and optionally starts a Flux agent.
encryptedpasswordEncrypts passwords to avoid storing them in plain text in the configuration file.
helpDisplays help messages for each command.

Creating a Flux Engine

To create a Flux engine from the command line, run the following command from the Flux home directory:

This command creates a standard Flux server using the default configuration file, engine-config.properties

You can also use this alternate syntax, which allows you to specify additional JVM parameters and class path settings:

In general, the flux.Main class provides the Flux command-line interface.

This command creates Flux using the specified Engine Configuration, in the stopped state. A stopped engine does not execute workflows.

To start the engine after creating it, include the start option on the command like, like so:

The start command allows your engine to execute workflows.

Starting, Stopping, and Shutting Down a Engine

Once you've created an engine, you can start, stop, and shut it down from a separate command line prompt. This is done using the client command.

To use the client command command to start an engine:

To stop the engine:

And, finally, to dispose:

Starting a Flux Agent

Like engines, Flux Agents can be started using the command line interface. To start an agent:

This command will start a Flux agent that registers with an engine located on the default port number at the host specified.

For more detailed information on starting an agent using the CLI, refer to the Flux Agent Architecture section of this manual, which provides further details on creating an agent.

More Command line options

Flux provides a robust interface accessible through the command line, but it is an often overlooked feature. This article will break down the various command and abilities available with the command line.

Basic Syntax

Nearly all tasks accomplished from the command line have the same basic syntax:

Agent-Server

The agent-server subsection on the command line is used to create agents. A complete list of options available for creating agents is available in Agents. Any options that are not specified will use their default values.

On the command-line, configuration settings share the name of their counterparts in the configuration file, but with the "_" characters removed – so "ENGINE_PORT" becomes "engineport", etc.

For Example:

Client

The client command on the command line allows you to manipulate the Flux engine. This command can perform tasks that are normally available through the Operations Console and API, like exporting workflows, expediting triggers, and retrieving general information about your workflows.

The following configuration options are available when invoking client commands. Any options that are not specified will use the default value.

OptionDescriptionExample
-hostThe host which is currently running the Flux engine you are trying to establish a connection to. Defaults to localhost.
-portThe port which the Flux engine is registered to. Defaults to 7520.
-cpThe path to the configuration file for your fluxEngine. This can replace any other configuration option.
-usernameThe username of a user within the system that has proper permissions to perform operations on workflows. Required when dealing with a secured engine.
-passwordPassword for the user. Required when attempting to negotiate with a secured engine.

 

 

-encryptedpasswordIf your password was encrypted using the Flux password encrypted (see the "encrypt-password" section of this article).

 

 

There are many client methods available to invoke:

MethodDescriptionExample
startStarts the engine to allow it to begin firing workflows.
stop

Stops the engine from proceeding with any work. The engine will still remain listening on the port to accept client and Operations Console connections, but will not run any workflows until it is started again. Disposing the engine will prevent it from listening on the port.

isrunning

Reports whether or not an engine is running at the location given by the specified configuration settings.

sizeReports how many workflows are running in the specified namespace.
expediteExpedites all workflows in the given namespace.
pausePauses all workflows in the given namespace.
resumeResumes all paused workflows in the given namespace.
removeRemoves all workflows in the given namespace.
interruptSends the interrupt signal to all workflows currently running in the given namespace.
exportExports the given workflow to the engine specified in the configuration options.
recover

For any flow contexts in the workflow that are in the ERROR or FAILED sub-state, the recover operation will roll back the flow context to the beginning of the transaction that caused the error condition. This will cause the flow context to begin executing again from the last successful transaction break it reached.



The server subsection of the command line interface deals directly with the creation of a Flux engine, and is therefore contains many of the most frequently invoked commands. Most configuration options for an engine are provided in a configuration file, so the options specified at the command line are fairly limited.

The only method available with the server command is "start".

The following table contains a comprehensive list of configuration options that can be set from the command line.

Refer below for a comprehensive list.

OptionDescriptionExample
-hostThe host name the engine is running on.
-portSpecifies the port the engine listens to on the localhost. Defaults to 7520.
-cpThe configuration file for the engine. Inside the file the bulk of the engine’s configuration options will be set. This includes, but is not limited to, database settings, security settings, and port settings.
-sslEnable SSL on the server. Defaults to true if not specified.

 

 

-usernameThe username used to log in to the engine. This is required if using a configuration file where security is enabled.
-passwordThe password used in conjunction with the username to log in to the engine. This is required is security is enabled. If not specified, prompts for password.
-encryptedpasswordIf you encrypted your password using the encryptpassword subsection of the command line interface, you will need to use this configuration option to pass it in. This is required if you are using security and want to obscure your password.

Encrypted Password

Flux provides a command line tool to encrypt your passwords for storage in configuration files, so you do not need to store plaintext passwords in the configuration or startup scripts.

Passwords can be easily encrypted from the command line:

The command will then print the encrypted password like so:

  • No labels