ecalsys_APP_ICON_h1 eCAL Sys CLI

eCAL Sys can be used purely from command line. The executable is ecal_sys /.exe. It can execute start / stop / restart commands provided from the command line or as well as from an interactive console. The interactive mode can also be used to automatize workflows by automatically piping commands to ecal_sys via stdin.

See also

eCAL Sys CLI cannot create .ecalsys files. Please use eCAL Sys GUI for that purpose.

eCAL Sys CLI features two modes:

  1. Direct mode (default):

    This mode lets you load a configuration and directly start or stop tasks.

  2. Remote control mode:

    This mode will connect to another eCAL Sys host application (GUI or CLI). Commands given to ecal_sys will then be forwarded to the remote-controlled eCAL Sys instance. Use this mode when you want to mainly use eCAL Sys manually (e.g. the GUI) but also automatically send commands to it in certain situation.




   ecal_sys  [-c <Path>] [--remote-control] [--remote-host <Hostname>] [-s]
             [-x] [-r] [--local-tasks-only <true|false>]
             [--use-localhost-for-all-tasks <true|false>]
             [--no-wait-for-clients] [--disable-update-from-cloud] [-i]
             [--interactive-dont-exit] [--] [--version] [-h]


   -c <Path>,  --config <Path>
     The Configuration file to load. Not supported in remote-control mode.

     Remote control another eCAL Sys instance.

   --remote-host <Hostname>
     Set the hostname for remote-controlling.

   -s,  --start
     Start all tasks.

   -x,  --stop
     Stop all tasks.

   -r,  --restart
     Restart all tasks.

   --local-tasks-only <true|false>
     Only tasks on local host will be considered. Not supported in
     remote-control mode.

   --use-localhost-for-all-tasks <true|false>
     All tasks will be considered as being on local host. Not supported in
     remote-control mode.

     Don't wait for eCAL Sys clients before starting / stopping tasks.
     Waiting is always disabled in interactive and remote-control mode.

     Do not use the monitor to update the tasks for

   -i,  --interactive
     Start eCAL Sys and listen for commands on stdin. When not in
     remote-control mode itself, eCAL Sys will offer the eCAL Sys Service
     for being remote-controlled. Note that eCAL Sys will exit, when stdin
     is closed. To prevent that, combine this option with
     "interactive-dont-exit". When using interactive mode, waiting for
     ecal_sys_clients is disabled.

     When in interactive mode, this option prevents eCAL Sys from exiting,
     when stdin is closed.

   --,  --ignore_rest
     Ignores the rest of the labeled arguments following this flag.

     Displays version information and exits.

   -h,  --help
     Displays usage information and exits.


Typical use-cases

The following examples are meant as an orientation how to use eCAL Sys.

Single-shot commands

Loading an .ecalsys file and starting / Stopping all tasks from it:

# Start:
ecal_sys -c ~/tutorial.ecalsys --start

# Stop:
ecal_sys -c ~/tutorial.ecalsys --stop

# Restart:
ecal_sys -c ~/tutorial.ecalsys --restart


ecal_sys will terminate once the command has been executed. Thus, terminating non-eCAL tasks will not work, as the new instance of ecal_sys that is responsible for stopping does not know the Process IDs.

Interactive mode

Launch the interactive mode to keep eCAL Sys running, while you can directly type commands. Type help to view a list of all commands available in interactive mode.

If you combine a single-shot command with the interactive mode, eCAL Sys will continue with the interactive mode after it has executed the command. eCAL Sys will not terminate on its own.

ecal_sys -c ~/tutorial.ecalsys --interactive

Available commands are:

  Quit eCAL Sys.

list [--tasks | --groups | --runners ] [ID or name]
  Prints a list of all tasks / groups / runners. If an ID or name is given,
  detailed information about that item are printed. If no argument --groups /
  --runners / --tasks is given, information about tasks are printed.

load <Path>
  Loads an eCAL Sys configuration file.

restart [IDs or names]
  Restart tasks with the given IDs or names. If no ID or name is given, all
  tasks will be restarted.

sleep <seconds>
  Sleeps for the given amount of time. Usefull when automatically piping input
  to eCAL Sys via stdin.

start [IDs or names]
  Start tasks with the given IDs or names. If no ID or name is given, all tasks 
  will be started.

stop [IDs or names]
  Stop tasks with the given IDs or names. If no ID or name is given, all tasks
  will be stopped.

  Updates the state of all (eCAL-) tasks that are visible, even if they have not
  been started by this eCAL Sys instance.


When starting terminal applications from the interactive mode, their STDOUT and STDERR will be printed in the ecal_sys terminal. This makes it very hard to enter another command or view information.

You may want to use another ecal_sys instance in remote-control mode to work around that issue.

Remote-control eCAL Sys

First you need something that can be remote controlled:

ecal_sys_gui ~/tutorial.ecalsys

# CLI (--interactive Flag will prevent the CLI from exiting)
ecal_sys -c ~/tutorial.ecalsys --interactive

Now you can use another instance of ecal_sys to remote-control that application. You can use single-shot commands, the interactive mode or both. In remote-control mode you cannot load an .ecalsys file, as this is done by the main application.

The following command will send the start command to your main application and then continue in interactive mode.

ecal_sys --remote-control --remote-host YOUR_HOSTNAME --start --interactive

Automatize eCAL Sys CLI

You can use the ecal_sys interactive mode to automatize it via STDIN. Commands are read line-by-line, i.e. they have to be divided by \n. Semicolons do not work. The most concise would probably be to write all your commands in a text file and pipe the content of that to ecal_sys.

  • Ubuntu:

    # Commands from command line:
    printf "Start \n Sleep 10 \n List \n Stop \n Sleep 5" | ecal_sys -c ~/tutorial.ecalsys --interactive
    # Commands from a file:
    cat commands.txt | ecal_sys -c ~/tutorial.ecalsys --interactive
  • Windows CMD.exe:

    rem Commands from command line:
    (echo Start & echo Sleep 10 & echo List & echo Stop & echo Sleep 5) | ecal_sys -c tutorial.ecalsys --interactive
    rem Commands from a file:
    more commands.txt | ecal_sys -c tutorial.ecalsys --interactive
  • Windows PowerShell:

    # Commands from command line:
    echo "Start `n Sleep 10 `n List `n Stop `n Sleep 5" | ecal_sys -c tutorial.ecalsys --interactive
    # Commands from a file:
    cat commands.txt | ecal_sys -c tutorial.ecalsys --interactive