Command line interface (CLI)

The ecFlow command line interface (CLI) is provided by the ecflow_client executable. A large number of commands/options enabled by the ecFlowUI are also available as CLI commands.

ecflow_client accepts a variety of commands, specified as --<command>. For example, the command --load can be used, as in the example below, to load the given file into the server.

ecflow_client --load host1.3141.check

The comprehensive list of ecflow_client commands is presented below. These commands can be combined with ecflow_client common options to further customise the ecflow_client behaviour.

Getting help

The list of commands, amongst other details, can be displayed by using the option --help.

ecflow_client --help

Using the ecFlow command line interface

• Handling CLI options
• Using ecflow_client in Tasks
• Using backup servers

Reference Commands

Table 2 List of ecflow_client commands

Command	Type	Description
abort	child command	Mark task as aborted. For use in the ‘.ecf’ script file only
alter	user command	Alter the node according to the options.
archive	user command	Archives suite or family nodes IF they have child nodes(otherwise does nothing).
begin	user command	Begin playing the definition in the server.
ch_add	user command	Add a set of suites, to an existing handle.
ch_auto_add	user command	Change an existing handle so that new suites can be added automatically.
ch_drop	user command	Drop/de-register the client handle.
ch_drop_user	user command	Drop/de-register all handles associated with the given user.
ch_register	user command	Register interest in a set of suites.
ch_rem	user command	Remove a set of suites, from an existing handle.
ch_suites	user command	Shows all the client handles, and the suites they reference
check	user command	Checks the expression and limits in the server. Will also check trigger references.
checkJobGenOnly	user command	Test hierarchical Job generation only, for chosen Node.
check_pt	user command	Forces the definition file in the server to be written to disk or allow mode,
complete	child command	Mark task as complete. For use in the ‘.ecf’ script file only
debug_server_off	user command	Disables debug output from the server
debug_server_on	user command	Enables debug output from the server
delete	user command	Deletes the specified node(s) or _ALL_ existing definitions( i.e delete all suites) in the server.
edit_history	user command	Returns the edit history associated with a Node.
edit_script	user command	Allows user to edit, pre-process and submit the script.
event	child command	Change event. For use in the ‘.ecf’ script file only
file	user command	Return the chosen file. Select from [ script<default> | job | jobout | manual | kill | stat ]
force	user command	Force a node to a given state, or set its event.
force-dep-eval	user command	Force dependency evaluation. Used for DEBUG only.
free-dep	user command	Free dependencies for a node. Defaults to triggers
get	user command	Get the suite definition or node tree in form that is re-parse able
get_state	user command	Get state data. For the whole suite definition or individual nodes.
group	user command	Allows a series of ‘;’ separated commands to be grouped and executed as one.
halt	user command	Stop server communication with jobs, and new job scheduling.
help	user command	Produce help message
init	child command	Mark task as started(active). For use in the ‘.ecf’ script file only
job_gen	user command	Job submission for chosen Node based on dependencies.
kill	user command	Kills the job associated with the node.
label	child command	Change Label. For use in the ‘.ecf’ script file only
load	user command	Check and load definition or checkpoint file into server.
log	user command	Get,clear,flush or create a new log file.
meter	child command	Change meter. For use in the ‘.ecf’ script file only
migrate	user command	Used to print state of the definition returned from the server to standard output.
msg	user command	Writes the input string to the log file.
news	user command	Returns true if state of server definition changed.
order	user command	Re-orders the nodes held by the server
ping	user command	Check if server is running on given host/port. Result reported to standard output.
plug	user command	Plug command is used to move nodes.
query	user command	Query the status of attributes
queue	child command	QueueCmd. For use in the ‘.ecf’ script file only
reloadcustompasswdfile	user command	Reload the server custom password file. For those user’s who don’t use login name
reloadpasswdfile	user command	Reload the server password file. To be used when ALL users have a password
reloadwsfile	user command	Reload the white list file.
remove	user command	remove variables i.e name name2
replace	user command	Replaces a node in the server, with the given path
requeue	user command	Re queues the specified node(s)
restart	user command	Start job scheduling, communication with jobs, and respond to all requests.
restore	user command	Manually restore archived nodes.
restore_from_checkpt	user command	Ask the server to load the definition from an check pt file.
resume	user command	Resume the given node. This allows job generation for the given node, or any child node.
run	user command	Ignore triggers, limits, time or date dependencies, just run the Task.
server_load	user command	Generates gnuplot files that show the server load graphically.
server_version	user command	Returns the version number of the server
show	user command	Used to print state of the definition returned from the server to standard output.
shutdown	user command	Stop server from scheduling new jobs.
stats	user command	Returns the server statistics as a string.
stats_reset	user command	Resets the server statistics.
stats_server	user command	Returns the server statistics as a struct and string. For test use only.
status	user command	Shows the status of a job associated with a task, in %ECF_JOB%.stat file
suites	user command	Returns the list of suites, in the order defined in the server.
suspend	user command	Suspend the given node. This prevents job generation for the given node, or any child node.
sync	user command	Incrementally synchronise the local definition with the one in the server.
sync_clock	user command	Incrementally synchronise the local definition with the one in the server.
sync_full	user command	Returns the full definition from the server.
terminate	user command	Terminate the server.
version	user command	Show ecflow client version number, and version of the boost library used
wait	child command	Evaluates an expression, and block while the expression is false.
why	user command	Show the reason why a node is not running.
zombie_adopt	user command	Locates the task in the servers list of zombies, and sets to adopt.
zombie_block	user command	Locates the task in the servers list of zombies, and sets flags to block it.
zombie_fail	user command	Locates the task in the servers list of zombies, and sets to fail.
zombie_fob	user command	Locates the task in the servers list of zombies, and sets to fob.
zombie_get	user command	Returns the list of zombies from the server.
zombie_kill	user command	Locates the task in the servers list of zombies, and sets flags to kill
zombie_remove	user command	Locates the task in the servers list of zombies, and removes it.

Reference Options

Table 3 List of common options for ecflow_client commands

Option	Description
add	Add variables e.g. name1=value1 name2=value2. Can only be used in combination with –init command.
debug	Enables the display of client environment settings and execution details.
host	When specified overrides the environment variable ECF_HOST and default host: ‘localhost’
http	Enables communication over HTTP between client/server.
https	Enables communication over HTTPS between client/server.
password	Specifies the password used to contact the server. Must be used in combination with option –user.
port	When specified overrides the environment variable ECF_PORT and default port: ‘3141’
rid	When specified overrides the environment variable ECF_RID. Can only be used for child commands.
ssl	Enables the use of SSL when contacting the server.
user	Specifies the user name used to contact the server. Must be used in combination with option –password.