.. _cmdline:

Commandline Arguments
=====================

The ``ImFusionSuite`` and ``ImFusionConsole`` executables both support various command-line arguments.

ImFusionConsole Executable
--------------------------

* --help                Show a help message.
* --execute arg         Run the given workspace file (.iws). Optionally
                        followed by ``key=value`` pairs for placeholders (also as
                        positional arguments).
* --batch arg           Load a placeholder batch file.
                        Example: ``ImFusionConsole MyWorkspace.iws
                        batch=batchfile.txt``, where batch file contains values for an arbitrary
                        number of placeholders, and each row will be run
                        separately.

                        Example batch file:

                        .. code-block::

                            InterpMode;Spacing
                            0;1.0
                            1;1.0

* --batchCase arg       Load a single case from the batch file (starting with
                        index 1).
                        Example: ``ImFusionConsole MyWorkspace.iws
                        --batch=batchfile.txt --batchCase=2``
* --licenseKey arg      Activate software (online).
* --licenseCode arg     Activate software (offline, used along with
                        ``--licenseKey``).

Note that workspace files can be passed to ``ImFusionConsole`` also as positional arguments. For example, ``ImFusionConsole MyWorkspace.iws key1=value1 key2=value2`` will load the given ImFusion Workspace without the need for any flags.


ImFusionSuite Executable
------------------------

* --help                        Show a help message.
*  --automatedUnitTest arg       Run unit tests temporarily resetting global
                                settings to their defaults -- needs to be
                                followed by a ``TestSuite`` and, optionally, a
                                ``TestCase``. The ``arg`` can be:

                                - ``'<Run all>'`` or ``''``: run all tests
                                - ``'Suite1, Suite2' '!Suite1::Test1, Suite2::Test2'``: run only the listed suites, but exclude the specified tests
                                - To run **all suites** but exclude individual tests, use ``'<Run all>' '!Suite1::Test1, Suite2::Test2'``
                                - ``'Suite1, Suite2' 'Suite1::Test1, Suite2::Test2'``: run only the listed tests within the listed suites

                                .. note::
                                   On Windows, replace single quotes (``'``) with double quotes (``"``) in cmd.exe.
*  --automatedUnitTestDev arg    Run unit tests *without* resetting global
                                settings to their defaults -- needs to be
                                followed by a ``TestSuite`` and, optionally, a
                                ``TestCase``. The ``arg`` can be:

                                - ``'<Run all>'`` or ``''``: run all tests
                                - ``'Suite1, Suite2' '!Suite1::Test1, Suite2::Test2'``: run only the listed suites, but exclude the specified tests
                                - To run **all suites** but exclude individual tests, use ``'<Run all>' '!Suite1::Test1, Suite2::Test2'``
                                - ``'Suite1, Suite2' 'Suite1::Test1, Suite2::Test2'``: run only the listed tests within the listed suites

                                .. note::
                                   On Windows, replace single quotes (``'``) with double quotes (``"``) in cmd.exe.

*  --closeAfterRunningWorkspace  Closes the Suite after running the Workspace
                                (.iws).
*  --execute arg                 Run the given workspace file (.iws). Optionally
                                followed by ``key=value`` pairs for placeholders
                                (also as positional arguments).
                                Example: ``./ImFusionSuite <path-to-iws-file>
                                key1=value1 key2=value2``
*  --load arg                    Loads all files passed next to the command-line
                                (also as positional arguments).
*  --test-plugin arg             Run unit tests from the test-plugin passed as
                                next argument. ``TestSuite`` and ``TestCase`` can
                                be specified.

Note that workspace files can be passed to ``ImFusionSuite`` also as positional arguments. For example, ``ImFusionSuite MyWorkspace.iws key1=value1 key2=value2`` will load the given ImFusion Workspace without the need for any flags.
The same holds if you want to load files, which can be passed as ``ImFusionSuite file1 file2 file3``.