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.
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:
|client||Runs a command on an existing Flux engine.|
|server||Administer (create, start, or stop) a Flux engine.|
|agent-client||Runs a command on an existing Flux agent.|
|agent-server||Creates and optionally starts a Flux agent.|
|encryptedpassword||Encrypts passwords to avoid storing them in plain text in the configuration file.|
|help||Displays 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.
Nearly all tasks accomplished from the command line have the same basic syntax:
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.
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.
|-host||The host which is currently running the Flux engine you are trying to establish a connection to. Defaults to localhost.|
|-port||The port which the Flux engine is registered to. Defaults to 7520.|
|-cp||The path to the configuration file for your fluxEngine. This can replace any other configuration option.|
|-username||The username of a user within the system that has proper permissions to perform operations on workflows. Required when dealing with a secured engine.|
|-password||Password for the user. Required when attempting to negotiate with a secured engine.|
|-encryptedpassword||If 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:
|start||Starts the engine to allow it to begin firing workflows.|
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.
Reports whether or not an engine is running at the location given by the specified configuration settings.
|size||Reports how many workflows are running in the specified namespace.|
|expedite||Expedites all workflows in the given namespace.|
|pause||Pauses all workflows in the given namespace.|
|resume||Resumes all paused workflows in the given namespace.|
|remove||Removes all workflows in the given namespace.|
|interrupt||Sends the interrupt signal to all workflows currently running in the given namespace.|
|export||Exports the given workflow to the engine specified in the configuration options.|
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.
|-host||The host name the engine is running on.|
|-port||Specifies the port the engine listens to on the localhost. Defaults to 7520.|
|-cp||The 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.|
|-ssl||Enable SSL on the server. Defaults to true if not specified.|
|-username||The username used to log in to the engine. This is required if using a configuration file where security is enabled.|
|-password||The 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.|
|-encryptedpassword||If 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.|
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: