Command internals

Warning

This is an internal developer reference, intended for developers and integrators working on the ecFlow client/server protocol itself, not for end users driving ecflow_client.

It documents the native client/server serialization (the on-the-wire request and reply payloads) alongside the C++ command classes that implement each command. Unlike the command line interface reference, this page is not auto-generated from ecflow_client; it is maintained by hand and may lag behind the current implementation. Treat the payloads and class references as illustrative of a particular server version rather than a stable, guaranteed contract.

This page is a reference for the commands understood by the ecFlow server. It provides a per-command reference, so that the description of each command, its options, and its wire representation stay consistent with the implementation.

Introduction

ecFlow follows a client/server model. The server (ecflow_server) holds the suite definition and the state of every node; the client (ecflow_client) issues commands that either query the server or change its state. Every interaction is a single round trip:

• the client sends a request — a client-to-server command, an instance of a class derived from ClientToServerCmd (.../libs/base/src/ecflow/base/cts/ClientToServerCmd.hpp);

• the server processes it and returns a reply — a server-to-client command, an instance of a class derived from ServerToClientCmd (.../libs/base/src/ecflow/base/stc/ServerToClientCmd.hpp).

Command-line model

The ecflow_client executable exposes each command as a long option. A single invocation carries exactly one command, optionally followed by that command’s own options and arguments, for example:

ecflow_client --init=$$
ecflow_client --alter change variable FOO bar /suite/family

The registry that maps each option to its command is .../libs/base/src/ecflow/base/cts/CtsCmdRegistry.cpp; the registration order there also fixes the order in which commands appear in ecflow_client --help. A few global options (--help, --version, --debug) apply to every command. A single command class frequently implements several options: for example CtsCmd covers --ping, --restart, --halt, --shutdown and --terminate, and PathsCmd covers --suspend, --resume, --kill and others.

Context supplied through the command line versus the environment

Command context reaches the client in two ways:

• Command-line options and arguments, parsed with Boost.Program_options. User commands take all of their context this way (paths, attribute names, values).

• Environment variables, read by ClientEnvironment (.../libs/client/src/ecflow/client/ClientEnvironment.cpp). Task commands rely almost entirely on these, because a job script does not know its own path or authentication token; the server writes them into the job at submission time.

Two groups of variables exist, matching the footer that ecflow_client --help prints for every command. The connection variables are used by every command, whether a user command or a task command:

Variable	Meaning
ECF_HOST	The main server hostname; default value is localhost.
ECF_PORT	The main server port; default value is 3141.
ECF_SSL	Enable secure (TLS) communication between the client and the server.
ECF_HOSTFILE	File that lists alternate hosts to try, if the connection to the main host fails.
ECF_HOSTFILE_POLICY	The policy (task or all) that defines which commands consider using alternate hosts.

ECF_HOST and ECF_PORT (or the equivalent --host / --port options) must be set for the client to reach the server; the others are optional.

The task-command variables are used additionally by every task command; the server writes them into the job at submission time:

Variable	Meaning
ECF_NAME	Full path name of the task, e.g. /suite/family/task.
ECF_PASS	The job password, defined by the server and used to authenticate task commands.
ECF_RID	The remote (process) identifier; supports identifying zombies and killing running jobs.
ECF_TRYNO	The run number of the job, used in job and output file-name generation.
ECF_TIMEOUT	Maximum time, in seconds, for the client to deliver a message to the server; default is 24 hours.
ECF_DENIED	Lets the task exit with an error on connection failure, instead of waiting for ECF_TIMEOUT.
NO_ECF	If set, ecflow_client exits immediately with success; useful for testing scripts without a server.

A custom user name may also be supplied through ECF_USER (or --user), in which case the matching password is read from the custom password file (ECF_CUSTOM_PASSWD); this is what populates the optional pswd_ and cu_ fields noted in Reading the payloads. The complete set of constants is declared in .../libs/core/src/ecflow/core/Environment.hpp. The per-command tables in the reference below highlight the variables each command reads directly; the connection variables above apply to every command throughout.

Task commands versus user commands

Commands fall into two families, mirrored by the source layout under .../libs/base/src/ecflow/base/cts/:

• Task commands (cts/task/) are issued from inside a .ecf job script, through the wrapper functions emitted by the job header. They report the progress of a running job and are authenticated with ECF_NAME + ECF_PASS + ECF_RID + ECF_TRYNO, all derived from the environment. All of them share the base class TaskCmd (cts/task/TaskCmd.hpp). The task commands are InitCmd, CompleteCmd, AbortCmd, EventCmd, MeterCmd, LabelCmd, QueueCmd and CtsWaitCmd.

• User commands (cts/user/) are issued by an operator or administrator to inspect or steer the server and its suites (begin, alter, force, delete, suspend, and so on). They share the base class UserCmd (cts/user/UserCmd.hpp) and are authenticated by user name.

Note

The request and reply payloads shown in this note are the native serialization used on the ecFlow client/server connection: the command object encoded as a cereal JSON archive (.../libs/core/src/ecflow/core/Serialization.hpp). This is distinct from the JSON of the optional REST API (ecflow_http), which is a separate, hand-written HTTP layer documented in the REST API reference.

Reading the payloads

On the wire a request is not the bare command but a small envelope. The client wraps the command in a ClientToServerRequest (member cmd_) and the server wraps its reply in a ServerToClientResponse (member stc_cmd_). cereal serialises the outermost object under a key derived from its mangled C++ type name (for example "21ClientToServerRequest"), and it renders a polymorphic pointer as a polymorphic_name (the concrete command class) plus a ptr_wrapper holding the object’s data. Inside data, base-class members appear first as nested value0 objects:

• for task commands, cl_host_ comes from ClientToServerCmd and path_to_submittable_, jobs_password_, process_or_remote_id_ and try_no_ come from TaskCmd;

• for user commands, cl_host_ comes from ClientToServerCmd and user_ comes from UserCmd (set when the request is dispatched). UserCmd also carries two optional fields, serialized only when set: pswd_, the user’s password, present when a password file supplies one (ECF_PASSWD, or ECF_CUSTOM_PASSWD for a custom user); and cu_, a flag that is true when a custom user name is in use (through --user, ECF_USER or the client API). The user-command examples in this note come from a server without password authentication configured, so they show user_ only; when a password is in play, a pswd_ field (and, for a custom user, cu_) appears alongside it.

The cereal_class_version and polymorphic_id fields are cereal bookkeeping. The payloads below are real serializer output, with host, password and user values replaced by placeholders.

Reference

For each command, the table summarises its type, class, action and inputs; the tabs that follow hold the command-line Usage, the serialized Request payload, and the serialized Reply payload. A command whose single class implements several actions adds a table of those actions before the tabs. A few commands carry an unbounded payload (an embedded definition or node subtree); these are described in prose instead of the tabbed layout.

Task commands

Command	Description
AbortCmd	Mark the task as aborted, with an optional reason.
CompleteCmd	Mark the task as complete, optionally removing variables.
CtsWaitCmd	Block the job until a trigger expression becomes true.
EventCmd	Set or clear an event on the task.
InitCmd	Mark the task as started (active), optionally adding variables.
LabelCmd	Update the value of a label on the task.
MeterCmd	Update the value of a meter on the task.
QueueCmd	Request or update a step of a queue.

AbortCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/AbortCmd.hpp
Action	--abort
Parameters	arg1 (optional): a free-text reason explaining why the abort was raised.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Marks the task as aborted. It is for use inside a .ecf script only, and is normally raised by the trap installed in the job header. When no reason is supplied the server records Trap raised in job file. The reason is sanitised on construction (newlines are stripped and semicolons replaced by spaces) so that it cannot corrupt the output of --migrate or --load. The zombie handling is the same as for InitCmd.

UsageHelpRequestReply

ecflow_client --abort=<some-reason>
# a bare --abort is valid; the server substitutes a default reason
ecflow_client --abort

CompleteCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/CompleteCmd.hpp
Action	--complete
Parameters	No positional argument. --remove (optional): a list of variable names to delete from the task.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Marks the task as complete. It is for use inside a .ecf script only. Where --init can add variables to a task, --complete can remove them, which is convenient for clearing per-run variables as the job finishes. The zombie handling is the same as for InitCmd.

UsageHelpRequestReply

ecflow_client --complete
# delete variables name1 and name2 from the task as it completes
ecflow_client --complete --remove name1 name2

CtsWaitCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/CtsWaitCmd.hpp
Action	--wait
Parameters	arg1 (mandatory): a trigger expression to evaluate.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Evaluates a trigger expression and blocks while it is false, returning to the job only once it becomes true. It is for use inside a .ecf script only, and is the mechanism behind script-level synchronisation on the state of other nodes.

UsageHelpRequestReply

ecflow_client --wait="/suite/taskx == complete"

EventCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/EventCmd.hpp
Action	--event
Parameters	arg1 (mandatory): the event name (or number). arg2 (optional): set or clear; defaults to set.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Sets or clears an event on the task. It is for use inside a .ecf script only. Unlike --init, --complete and --abort, the default zombie action is to fob (allow the client command to complete without error); this can be overridden with zombie attributes.

UsageHelpRequestReply

ecflow_client --event=ev         # set the event (the default)
ecflow_client --event=ev set     # set the event, explicit
ecflow_client --event=ev clear   # clear the event

InitCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/InitCmd.hpp
Action	--init
Parameters	arg1 (mandatory): the process or remote identifier of the job (typically the shell $$), which the server stores so the job can later be killed. --add (optional): a list of name=value pairs to add to, or update on, the task.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_TRYNO — current try number. ECF_RID — when set, cross-checked against arg1; the two must match.

Marks the task as started (state active). It is for use inside a .ecf script only. When the task command is detected as a zombie the default action is to block; this can be overridden with zombie attributes, and the blocking period is bounded by ECF_TIMEOUT.

UsageHelpRequestReply

ecflow_client --init=$$
# add or update variables on the task at the same time
ecflow_client --init=$$ --add name=value name2=value2

LabelCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/LabelCmd.hpp
Action	--label
Parameters	arg1 (mandatory): the label name. arg2 (mandatory): the new label value; may be a single word or a multi-line, space-separated set of quoted strings.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Updates the value of a label on the task. It is for use inside a .ecf script only. The default zombie action is to fob.

UsageHelpRequestReply

ecflow_client --label=progressed merlin

MeterCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/MeterCmd.hpp
Action	--meter
Parameters	arg1 (mandatory): the meter name. arg2 (mandatory): the new meter value (integer).
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Updates the value of a meter on the task. It is for use inside a .ecf script only. The default zombie action is to fob.

UsageHelpRequestReply

ecflow_client --meter=my_meter 20

QueueCmd

Type	Task command
C++ class	.../libs/base/src/ecflow/base/cts/task/QueueCmd.hpp
Action	--queue
Parameters	arg1 (mandatory): the queue name. arg2 (mandatory): the action, one of active, aborted, complete, no_of_aborted or reset. arg3 (step): required by complete and aborted; the step value returned by a previous active call. arg4 (path, optional): the node holding the queue; by default the queue is searched for up the node tree.
Environment variables	ECF_NAME — absolute path of the task. ECF_PASS — job password used for authentication. ECF_RID — remote (process) identifier of the job. ECF_TRYNO — current try number.

Cooperates with a queue attribute to hand out steps to a running job. active returns the first queued or aborted step and advances the index; no_of_aborted returns the count of aborted steps; reset rewinds the index so steps can be reprocessed; complete and aborted mark the given step. It is for use inside a .ecf script only, and the default zombie action is to block. The active and no_of_aborted actions return a string; the others return the generic reply.

UsageHelpRequestReply

QNAME=my_queue
# obtain and activate the next step; returns e.g. "003", or "<NULL>" when exhausted
step=$(ecflow_client --queue=$QNAME active)
# after processing, mark the step complete (or aborted on failure)
ecflow_client --queue=$QNAME complete $step

User commands

Several user commands implement a whole family of operations in a single class, dispatched by an enumerated discriminator carried in the payload — for example api_ for CtsCmd, CtsNodeCmd, PathsCmd, LogCmd, ClientHandleCmd and CSyncCmd, the add_attr_type_ / change_attr_type_ / del_attr_type_ fields for AlterCmd, and user_action_ for ZombieCmd. For these, the individual actions differ only in that field and in the accompanying paths, names and values, so each is documented with a table of its actions followed by one or two representative payloads rather than a payload per action. AlterCmd and CtsCmd are the two largest. The commands below are listed alphabetically.

Command	Description
AlterCmd	Add, change, delete or sort an attribute on nodes.
BeginCmd	Begin one or all suites.
CFileCmd	Retrieve a node’s script, job, output, manual or kill/status file.
CheckPtCmd	Checkpoint the server, optionally changing the checkpoint mode.
ClientHandleCmd	Manage client handles (per-client suite subsets) used for synchronisation.
CSyncCmd	Synchronise a client with the server’s state.
CtsCmd	Argument-less server signals (ping, restart, halt, stats, and so on).
CtsNodeCmd	Query a node or the definition (get, why, get_state, migrate, and so on).
DeleteCmd	Delete nodes, or every suite.
EditScriptCmd	Retrieve or submit a task’s script, with optional preprocessing.
ForceCmd	Force a node into a state, or force an event.
FreeDepCmd	Free a held dependency so a node may run.
GroupCTSCmd	Bundle several commands into a single request.
LoadDefsCmd	Load a suite definition into the server.
LogCmd	Inspect or manage the server log file.
LogMessageCmd	Write a message into the server log.
MoveCmd	Transfer a node subtree between locations or servers (internal).
OrderNodeCmd	Change a node’s position among its siblings.
PathsCmd	Node operations (suspend, resume, kill, status, check, archive, and so on).
PlugCmd	Move a node subtree to a new parent, possibly on another server.
QueryCmd	Read a single piece of node state without changing anything.
ReplaceNodeCmd	Replace or add a node using another definition.
RequeueNodeCmd	Requeue nodes so they may run again.
RunNodeCmd	Run a task immediately, bypassing its time dependencies.
ServerVersionCmd	Return the server version string.
ShowCmd	Select the client print style (client-side).
ZombieCmd	Resolve zombies (fob, fail, adopt, remove, block, kill).

AlterCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/AlterCmd.hpp
Action	--alter
Parameters	arg1 (operation): one of add, change, delete, sort, set_flag or clear_flag. arg2 (attribute type): the kind of attribute to operate on (see the Attribute types table below). name / value (operation-dependent): the attribute name and value; several attribute types take only a name, and delete with no name removes every attribute of that type. paths (one or more): the nodes to which the alteration applies.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Adds, changes, deletes or sorts an attribute on one or more nodes. It is the primary command for editing a running suite. The general form is --alter <operation> <attribute-type> [name] [value] <path> [<path> ...]. The attribute types accepted by each operation are:

Operation	Attribute types
add	time, today, date, day, zombie, variable, late, limit, inlimit, label, aviso, mirror, event, meter
change	variable, clock_type, clock_date, clock_gain, clock_sync, event, meter, label, trigger, complete, repeat, limit_max, limit_value, defstatus, late, time, today, aviso, mirror
delete	variable, time, today, date, day, cron, event, meter, label, trigger, complete, repeat, limit, limit_path, inlimit, zombie, late, queue, generic, aviso, mirror
sort	event, meter, label, limit, variable, all
set_flag / clear_flag	a node flag, carried by flag_type_ and flag_ rather than by an attribute type

Every AlterCmd payload carries the same fields; the operation is encoded by the discriminator integers, and any discriminator not in use holds its “not set” sentinel value (add_attr_type_ 6, del_attr_type_ 16, change_attr_type_ 13, flag_type_ 19). For add, change and delete exactly one of add_attr_type_ / change_attr_type_ / del_attr_type_ selects the attribute type. For set_flag and clear_flag the flag is carried by flag_type_, and flag_ selects set (true) versus clear (false). For sort all attribute discriminators stay at their sentinel and name_ holds the attribute type (with value_ optionally recursive).

UsageHelpRequestReply

ecflow_client --alter change variable FOO bar /suite/family
ecflow_client --alter add label info "hello world" /suite/family/task
# delete every variable on the node (no name given)
ecflow_client --alter delete variable /suite
# sort the variables of the node and its children
ecflow_client --alter sort variable recursive /suite/family
# set and clear a node flag
ecflow_client --alter set_flag late /suite/family
ecflow_client --alter clear_flag late /suite/family

BeginCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/BeginCmd.hpp
Action	--begin
Parameters	arg1 (optional): the suite to begin; when omitted every suite is begun. force (optional): begin even when the suite is already begun, discarding its state.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Begins one or all suites, moving them from the definition into a running state so that scheduling starts. The force flag is stored in force_; the request below is for --begin s1 and the --begin s1 --force variant differs only in force_ being true.

UsageHelpRequestReply

ecflow_client --begin s1
ecflow_client --begin s1 --force
ecflow_client --begin            # begin all suites

CFileCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/CFileCmd.hpp
Action	--file
Parameters	arg1 (node path): the node whose file is requested. arg2 (file type): one of script/ecf (file_ 0), job (1), jobout (2), manual (3), kill (4) or stat (5). arg3 (max lines, optional): the maximum number of lines to return.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Retrieves one of the files associated with a node (the script, the generated job, its output, the manual page, or the output of the kill/status commands). The file type is carried by file_ and the line limit by max_lines_. The reply is always a string.

UsageHelpRequestReply

ecflow_client --file /suite/family/task jobout 100
ecflow_client --file /suite/family/task script

CheckPtCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/CheckPtCmd.hpp
Action	--check_pt
Parameters	mode (optional): never (mode_ 0), on_time (1) or always (2); 3 is the undefined sentinel. interval (optional): the checkpoint interval in seconds (check_pt_interval_). alarm (optional): the save-time alarm in seconds (check_pt_save_time_alarm_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Triggers a checkpoint of the server state, and optionally changes the checkpoint mode, interval and save-time alarm. Called with no argument it checkpoints immediately.

UsageHelpRequestReply

ecflow_client --check_pt
ecflow_client --check_pt=always:120:30

ClientHandleCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/ClientHandleCmd.hpp
Action	one option per handle operation (see the Actions table below)
Parameters	client_handle (most actions): the handle identifier (client_handle_). suites (register/add): the suites to associate with the handle (suites_). auto_add_new_suites (register): whether new suites are added automatically (auto_add_new_suites_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Manages client handles: server-side registrations that let a client (typically ecflow_ui) track a chosen subset of suites and receive only their changes. The operation is carried by api_:

Option	api_	Description	Reply
--ch_register	0	Register a new handle for a set of suites.	handle
--ch_drop	1	Drop a handle.	StcCmd (OK)
--ch_drop_user	2	Drop all handles owned by a user.	StcCmd (OK)
--ch_add	3	Add suites to a handle.	StcCmd (OK)
--ch_rem	4	Remove suites from a handle.	StcCmd (OK)
--ch_auto_add	5	Change the auto-add-new-suites flag of a handle.	StcCmd (OK)
--ch_suites	6	List registered handles and their suites.	suites

UsageHelpRequestReply

ecflow_client --ch_register 1 /s1 /s2
ecflow_client --ch_drop 1

CSyncCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/CSyncCmd.hpp
Action	one option per synchronisation mode (see the Actions table below)
Parameters	client_handle (optional): the handle whose suites are synchronised (client_handle_). client_state_change_no / client_modify_change_no: the change numbers the client already holds, so the server can compute an incremental update.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Keeps a client in step with the server. It is issued repeatedly by clients such as ecflow_ui rather than typed by an operator. The mode is carried by api_:

Option	api_	Description	Reply
--news	0	Ask whether anything has changed since the given change numbers.	news
--sync	1	Return an incremental update.	sync
--sync_full	2	Return the full definition.	sync
--sync_clock	3	Return a clock-only update.	sync

UsageHelpRequestReply

# issued internally by clients; not normally typed directly
ecflow_client --sync 1 10 5

CtsCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/CtsCmd.hpp
Action	one option per server signal (see the Actions table below)
Parameters	none; each action is a bare signal to the server.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Encapsulates the many simple, argument-less signals to the server in a single class, to limit the number of global serialisation symbols. Each command-line option maps to one value of the Api enumeration, carried in the payload as api_. Most actions return the generic success reply; a few return a string or a structured reply, as noted in the table:

Option	api_	Description	Reply
--restore_from_checkpt	1	Restore the definition from the checkpoint file.	StcCmd (OK)
--restart	2	Restart the server (resume scheduling).	StcCmd (OK)
--shutdown	3	Stop scheduling new jobs; keep serving requests.	StcCmd (OK)
--halt	4	Stop scheduling and stop most request handling.	StcCmd (OK)
--terminate	5	Terminate the server process.	StcCmd (OK)
--reloadwsfile	6	Reload the white-list file.	StcCmd (OK)
--force-dep-eval	7	Force an immediate dependency evaluation.	StcCmd (OK)
--ping	8	Check that the server is reachable.	StcCmd (OK)
--zombie_get	9	Retrieve the list of zombies.	zombie list
--stats	10	Return server statistics as text.	string
--suites	11	Return the list of suites as text.	string
--debug_server_on	12	Enable server-side debug output.	StcCmd (OK)
--debug_server_off	13	Disable server-side debug output.	StcCmd (OK)
--server_load	14	Return the path of the log file for load plotting.	server load
--stats_reset	15	Reset the server statistics.	StcCmd (OK)
--reloadpasswdfile	16	Reload the password file.	StcCmd (OK)
--stats_server	17	Return the statistics structure (test use only).	stats structure
--reloadcustompasswdfile	18	Reload the custom-user password file.	StcCmd (OK)

UsageHelpRequestReply

ecflow_client --ping
ecflow_client --restart
ecflow_client --suites

CtsNodeCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/CtsNodeCmd.hpp
Action	one option per query (see the Actions table below)
Parameters	arg1 (optional node path): the node to query; when omitted the whole definition is used.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Queries the server about a node or the whole definition. The query is carried by api_ and the target by absNodePath_:

Option	api_	Description	Reply
--job_gen	1	Force job generation under the node.	StcCmd (OK)
--check_job_gen_only	2	Test job generation without submitting.	StcCmd (OK)
--get	3	Return the definition (or node subtree).	definition
--why	4	Explain why a node is not running.	string
--get_state	5	Return the definition with node states.	definition
--migrate	6	Return a representation suitable for migration.	string

UsageHelpRequestReply

ecflow_client --why=/suite/family/task
ecflow_client --get=/suite/family/task

DeleteCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/DeleteCmd.hpp
Action	--delete
Parameters	arg1 (mandatory): _all_ to delete every suite, or one or more node paths. force (optional): delete even nodes that are active or submitted. yes (optional): skip the interactive confirmation prompt.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Removes nodes from the server. The paths are carried in paths_ and the force flag in force_. Deleting every suite (--delete _all_) returns a distinct reply.

UsageHelpRequestReply

ecflow_client --delete=/suite/family
ecflow_client --delete force yes /suite/family/task
ecflow_client --delete _all_

EditScriptCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/EditScriptCmd.hpp
Action	--edit_script
Parameters	arg1 (node path): the task whose script is edited (path_to_node_). arg2 (sub-command): selects the operation, encoded in edit_type_ — edit (0), pre_process (1), submit (2), pre_process_file (3) or submit_file (4). additional arguments carry a user file (user_file_contents_), user variables (user_variables_), and the alias_ / run_ flags.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Retrieves or submits the script of a task, with optional preprocessing and variable substitution. It underlies the “edit script” workflow in ecflow_ui.

UsageHelpRequestReply

ecflow_client --edit_script /suite/family/task pre_process > script.pp

ForceCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/ForceCmd.hpp
Action	--force
Parameters	arg1 (state or event): a node state (unknown, complete, queued, submitted, active, aborted) or a <path>:<event> with set / clear. recursive (optional): apply to the node and all of its children. full (optional): together with recursive, set repeats to their last value. paths (one or more): the nodes to force.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Forces a node into a given state, or forces an event, regardless of dependencies. stateOrEvent_ holds the requested state or event, and recursive_ / setRepeatToLastValue_ carry the recursive and full modifiers.

UsageHelpRequestReply

ecflow_client --force complete /suite/family/t1 /suite/family/t2
ecflow_client --force recursive full complete /suite/family
ecflow_client --force clear /suite/family/t1:myevent

FreeDepCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/FreeDepCmd.hpp
Action	--free-dep
Parameters	paths (one or more): the nodes whose dependencies are freed. trigger / all / date / time (optional flags): which dependencies to free; trigger is the default (trigger_), all frees every kind, and date / time free the respective time dependencies.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Frees a node from a held dependency so that it may run, without changing the dependency itself. The flags select which dependency kinds are freed.

UsageHelpRequestReply

ecflow_client --free-dep /suite/family/task
ecflow_client --free-dep trigger date time /suite/family/task

GroupCTSCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/GroupCTSCmd.hpp
Action	--group
Parameters	arg1 (mandatory): a semicolon-separated list of commands to run as one unit (cmdVec_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Bundles several commands into a single request so that they are sent and executed together. Each member command is serialized as a polymorphic entry of cmdVec_; cli_ records whether the group originated on the command line.

UsageHelpRequestReply

ecflow_client --group="ping; get=/suite"

LoadDefsCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/LoadDefsCmd.hpp
Action	--load
Parameters	arg1 (mandatory): the definition file to load. force (optional): overwrite suites that already exist (force_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Loads a suite definition into the server. The client reads the file and embeds its serialized form in defs_; defs_filename_ records the original file name. The defs_ field is a complete serialized definition and can be large; it is truncated below.

UsageHelpRequestReply

ecflow_client --load=my_suite.def
ecflow_client --load=my_suite.def force

LogCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/LogCmd.hpp
Action	--log
Parameters	arg1 (sub-command): get (api_ 0), clear (1), flush (2), new (3) or path (4). get_last_n_lines (optional, get only): how many trailing lines to return (get_last_n_lines_, default 100). new_path (optional, new only): the path of the new log file (new_path_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Inspects or manages the server log file. get and path return a string; clear, flush and new return the generic reply.

UsageHelpRequestReply

ecflow_client --log=get 200
ecflow_client --log=clear
ecflow_client --log=path

LogMessageCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/LogMessageCmd.hpp
Action	--msg
Parameters	arg1 (mandatory): the message to write to the server log (msg_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Writes an arbitrary message into the server log file, useful for annotating operations.

UsageHelpRequestReply

ecflow_client --msg="starting the morning cycle"

MoveCmd

Type	User command (internal)
C++ class	.../libs/base/src/ecflow/base/cts/user/MoveCmd.hpp
Action	none (internal)
Parameters	src_node_: the serialized source node subtree. src_host_ / src_port_ / src_path_: the origin server and path. dest_: the destination parent path.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Carries a node subtree from one location (or server) to another. It has no command-line option of its own: it is generated by PlugCmd and by drag-and-drop in ecflow_ui. The src_node_ field embeds the serialized subtree, so the payload is unbounded; its structure mirrors the other user commands, with the base-class cl_host_ and user_ followed by the fields above. The reply is the generic StcCmd success reply with api_ equal to 0.

OrderNodeCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/OrderNodeCmd.hpp
Action	--order
Parameters	arg1 (node path): the node to reorder among its siblings (absNodepath_). arg2 (order): top (option_ 0), bottom (1), alpha (2), order (3), up (4), down (5) or runtime (6).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Changes the position of a node among its siblings, which determines display order and, for some attributes, evaluation order. The ordering is carried by option_.

UsageHelpRequestReply

ecflow_client --order=/suite/family/task top

PathsCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/PathsCmd.hpp
Action	one option per node operation (see the Actions table below)
Parameters	paths (one or more): the nodes to operate on. force (optional, --kill only): kill even when already being killed.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Applies a common node operation to one or more paths. The operation is carried by api_ and the targets by paths_:

Option	api_	Description	Reply
--suspend	1	Suspend the node, preventing it from being scheduled.	StcCmd (OK)
--resume	2	Resume a suspended node.	StcCmd (OK)
--kill	3	Run ECF_KILL_CMD for the node’s active jobs.	StcCmd (OK)
--status	4	Run ECF_STATUS_CMD to query job status.	string
--check	5	Check trigger and other expressions resolve.	string
--edit_history	6	Return the edit history of the node.	string
--archive	7	Archive the node’s children to disk.	StcCmd (OK)
--restore	8	Restore previously archived children.	StcCmd (OK)

UsageHelpRequestReply

ecflow_client --suspend /suite/family
ecflow_client --check /suite/family

PlugCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/PlugCmd.hpp
Action	--plug
Parameters	arg1 (source): the node subtree to move (source_). arg2 (destination): the target parent, optionally on another server as //host:port/path (dest_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Moves a node subtree to a new parent, possibly on a different server. Internally the server uses MoveCmd to transfer the subtree to the destination.

UsageHelpRequestReply

ecflow_client --plug /suite/family //host:3141/dest

QueryCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/QueryCmd.hpp
Action	--query
Parameters	arg1 (query type): one of state, dstate, event, meter, label, variable, trigger, repeat, limit or limit_max (query_type_). arg2 (path): the node, or <path>:<attribute>, being queried (path_to_attribute_ and attribute_). arg3 (optional task path): the task the query is made on behalf of (path_to_task_), used for logging.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Reads a single piece of state from the server without changing anything — for example the state of a node, or the value of an event, meter or variable. The reply is always a string. It is often used inside scripts to branch on a node’s state.

UsageHelpRequestReply

ecflow_client --query state /suite/family/task
ecflow_client --query event /suite/family/task:myevent

ReplaceNodeCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/ReplaceNodeCmd.hpp
Action	--replace
Parameters	arg1 (node path): the node to replace (pathToNode_). arg2 (definition file): the source definition (path_to_defs_); its serialized form is embedded in clientDefs_. parent (optional): create parent nodes as needed (createNodesAsNeeded_). force (optional): replace even active or submitted nodes (force_).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Replaces a node (or adds it) using a node of the same path taken from another definition. Like LoadDefsCmd, the source definition is embedded as a serialized string, here in clientDefs_, which can be large. The payload therefore has the following structure (clientDefs_ elided):

{
  "21ClientToServerRequest": {
    "cmd_": {
      "polymorphic_id": 2147483649,
      "polymorphic_name": "ReplaceNodeCmd",
      "ptr_wrapper": {
        "id": 2147483649,
        "data": {
          "cereal_class_version": 0,
          "value0": {
            "cereal_class_version": 0,
            "value0": { "cereal_class_version": 0, "cl_host_": "host.example.com" },
            "user_": "operator"
          },
          "createNodesAsNeeded_": true,
          "force_": false,
          "pathToNode_": "/suite/family",
          "path_to_defs_": "my_suite.def",
          "clientDefs_": "#5.18.0\nsuite suite\n  family family\n    task t1\n  endfamily\nendsuite\n# ..."
        }
      }
    }
  }
}

The reply is the generic StcCmd success reply with api_ equal to 0.

Verbatim ecflow_client --replace output (the common environment-variable footer is omitted):

replace
-------

Replaces a node in the server, with the given path
Can also be used to add nodes in the server
  arg1 = path to node
         must exist in the client defs(arg2). This is also the node we want to
         replace in the server
  arg2 = path to client definition file
         provides the definition of the new node
  arg3 = (optional) [ parent | false ] (default = parent)
         create parent families or suite as needed, when arg1 does not
         exist in the server
  arg4 = (optional) force (default = false)
         Force the replacement even if it causes zombies to be created
Replace can fail if:
- The node path(arg1) does not exist in the provided client definition(arg2)
- The client definition(arg2) must be free of errors
- If the third argument is not provided, then node path(arg1) must exist in the server
- Nodes to be replaced are in active/submitted state, in which case arg4(force) can be used

Replace will preserve the suspended status, if this is not required please re-queue first
After replace is done, we check trigger expressions. These are reported to standard output.
It is up to the user to correct invalid trigger expressions, otherwise the tasks will *not* run.
Please note, you can use --check to check trigger expression and limits in the server.
For more information use --help check.

Usage:
  --replace=/suite/f1/t1 /tmp/client.def  parent      # Add/replace node tree /suite/f1/t1
  --replace=/suite/f1/t1 /tmp/client.def  false force # replace t1 even if its active or submitted

RequeueNodeCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/RequeueNodeCmd.hpp
Action	--requeue
Parameters	option (optional): abort requeues only aborted tasks; force requeues even active or submitted tasks. The default is no option (option_ 0). paths (one or more): the nodes to requeue.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Requeues nodes so that they may run again. option_ encodes the modifier (0 none, 1 abort, 2 force).

UsageHelpRequestReply

ecflow_client --requeue /suite/family
ecflow_client --requeue abort /suite/family
ecflow_client --requeue force /suite/family/task

RunNodeCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/RunNodeCmd.hpp
Action	--run
Parameters	paths (one or more): the tasks to run immediately. force (optional): run even when a dependency would hold the task.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Runs a task immediately, bypassing its scheduling time. force_ records whether dependencies are ignored.

UsageHelpRequestReply

ecflow_client --run /suite/family/task
ecflow_client --run force /suite/family/task

ServerVersionCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/ServerVersionCmd.hpp
Action	--server_version
Parameters	none.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Returns the version string of the running server. The command carries no fields of its own, so the payload holds only the base-class cl_host_ and user_.

UsageHelpRequestReply

ecflow_client --server_version

ShowCmd

Type	User command (client-side)
C++ class	.../libs/base/src/ecflow/base/cts/user/ShowCmd.hpp
Action	--show
Parameters	arg1 (optional style): the print style to apply to the output (defs, state, migrate, and so on).
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Selects the print style used when the client renders a definition, and is normally combined with a retrieval command such as --get in a group. The chosen style is applied on the client side and is not part of the serialized payload, so the request carries only the base-class cl_host_ and user_.

UsageHelpRequestReply

ecflow_client --group="get=/suite; show=state"

ZombieCmd

Type	User command
C++ class	.../libs/base/src/ecflow/base/cts/user/ZombieCmd.hpp
Action	one option per zombie resolution (see the Actions table below)
Parameters	paths (one or more): the zombies to act on. process_id / password (internal): populated when the action originates from a task command rather than the command line.
Environment variables	ECF_USER (optional): overrides the authenticated user name.

Resolves zombies: mismatches between a running job and the server’s record of a task. The action is carried by user_action_:

Option	user_action_	Description
--zombie_fob	0	Allow the task command to complete without changing state.
--zombie_fail	1	Make the task command fail.
--zombie_adopt	2	Adopt the zombie, applying its state change to the task.
--zombie_remove	3	Remove the zombie from the server’s list.
--zombie_block	4	Block the task command until a decision is made.
--zombie_kill	5	Run the kill command against the zombie’s process.

UsageHelpRequestReply

ecflow_client --zombie_fob /suite/family/task
ecflow_client --zombie_kill /suite/family/task