.. include:: ../macros.hrst
.. include:: ../abbreviations.hrst

.. _chapter:CommandLineArguments:

Command Line Arguments
######################

Command-line arguments offer control over runtime application behavior and configuration of
settings, and integrate easily with scripts or automated pipelines. All |ParaView| executables,
detailed in :numref:`sec:ParaViewExecutables`, share a common set of command-line options, although
each program also supports unique arguments specific to its functionality.

The following basic syntax rules apply to all |ParaView| executables:

* Values for options can be provided after a space or an equals sign.

    * ``--option value`` is equivalent to ``--option=value``.

* For options that accept multiple values, denoted ``--moption TYPE ...``, you can either provide
  the option multiple times or separate the values with a comma.

    * ``--moption=foo --moption=bar`` is equivalent to ``--moption=foo,bar``.

* Options may expect a certain type of value.

    * ``TEXT``: A text string.
    * ``INT``: An integer number.
    * ``FLOAT``: A floating-point number.
    * ``ENUM``: One of several predefined values.

.. _sec:CommonCommandLineArguments:

Common Options
==============

The options below are common to all |ParaView| executables: |paraview|, |pvpython|, |pvbatch|,
|pvserver|, |pvdataserver| and |pvrenderserver|.

**General options**:

* ``-h``, ``--help``: Prints the help message and exit.
* ``-V``, ``--version``: Prints version number and exit.
* ``-v``, ``--verbosity ENUM:verbosity``: Controls log verbosity on stderr, using integer values in
  the range ``[-9, 9]`` or one of ``INFO``, ``WARNING``, ``ERROR``, or ``OFF``. Defaults to
  ``INFO(0)``.
* ``-d``, ``--dr``, ``--disable-registry``: Skips user-specific applications settings and
  configuration options.
* ``--print-monitors``: Prints monitor information and exit. This option is only available on Windows.
* ``--venv TEXT``: Initializes python with a virtual environment at this path.

**Debugging and logging options**:

* ``--enable-bt``: Generates stack-trace on crash, if possible.
* ``--cslog TEXT``: Specifies the filename to use for generating a ClientServerStream log.
* ``-l``, ``--log TEXT[,ENUM:verbosity] ...``:  Additional log files to generate. Can be specified
  multiple times. By default, log verbosity is set to ``INFO(0)`` and may be overridden per file by
  adding suffix ``,verbosity``, where verbosity values are same as those accepted for the
  ``--verbosity`` argument.

**MPI options**:

* ``--mpi``: Initializes MPI for the current process, even if not necessary.

  * Excludes: ``--no-mpi``.

* ``--no-mpi``: Skips initializing MPI on current process, if not required.

  * Excludes: ``--mpi``.

* ``--use-mpi-ssend``: Use ``MPI_SSend`` instead of ``MPI_Send``, whenever possible. Useful for
  debugging race conditions in distributed environments.

  * This setting can also be configured via the ``PARAVIEW_USE_MPI_SSEND`` environment variable.

**Plugin options**:

* ``--plugins TEXT ...``: Specify plugins to load on startup.
* ``--plugin-search-paths TEXT ...``:  Specify search paths for plugins when resolving plugin names.

**Connection options**:

* ``--connect-id INT``: An identifier used to match client-server connections. Non-zero values
  require the client and server to use the same identifier. Default is ``0``.
* ``--hostname TEXT``: Override the hostname used for connecting to this process. By default, the
  hostname is determined using appropriate system calls.

**Rendering options** (for all but |pvdataserver|):

* ``--force-offscreen-rendering``: If supported by the build and platform, creates headless
  (offscreen) render windows for rendering results.

  * Excludes: ``--force-onscreen-rendering``.

* ``--force-onscreen-rendering`` : If supported by the build and platform, creates on-screen render
  windows.

  * Excludes ``--force-offscreen-rendering``.
  * This setting can also be configured via the ``PV_DEBUG_REMOTE_RENDERING`` environment variable.

* ``--opengl-window-backend ENUM`` Specify the OpenGL window backend to use. Supported values are
  ``GLX``, ``EGL``, ``OSMesa``, ``Win32``. This option is only relevant for |pvbatch|, |pvpython|,
  |pvserver|, and |pvrenderserver|.

  * If not specified, the default backend is determined by the build and hardware configuration.

**Display environment options** (for all but |pvdataserver|):

* ``--disable-xdisplay-test``: Skips all X-display tests and OpenGL version checks. This is only
  applicable on systems with X. Use this if you're confident that your X environment and OpenGL
  support are set up correctly (experimental).
* ``--displays TEXT ...``: Specify a list of rendering display or device ids. For X-based systems,
  this can be the value to set for the ``DISPLAY`` environment. For EGL-based systems, these are the
  available EGL device indices. When specified these are distributed among the number of rendering
  ranks using ``--displays-assignment-mode`` specified.
* ``--displays-assignment-mode ENUM``: Specify how to assign displays (specified using
  ``--displays=``) among rendering ranks. Supported values are ``round-robin`` (default) and
  ``contiguous``.

  * Needs: ``--displays``.

**Stereo rendering options** (for all but |pvdataserver|):

* ``--stereo``: Enables stereo rendering.
* ``--stereo-type INT``: Specify the stereo type to use. Possible values are ``Crystal Eyes``,
  ``Red-Blue``, ``Interlaced``, ``Dresden``, ``Anaglyph``, ``Checkerboard``, or
  ``SplitViewportHorizontal``.

  * Needs: ``--stereo``.

* ``--eye-separation FLOAT``: Specify eye separation distance.

  * Needs: ``--stereo``.

.. _sec:paraviewCommandLineArguments:

|paraview|-Specific Options
===========================

**Arguments controlling actions on application launch**:

* ``filenames TEXT ...``: Positional arguments that may be used to pass either data, state, or
  script files. ``.pvsm`` files are treated as state files, ``.py`` are treated as scripts and all
  others are treated as data files.

  * Excludes: ``--state``, ``--script``, ``--data``.

* ``--state TEXT`` State file (``.pvsm`` or ``.py``) to load when the application starts.

  * Excludes: ``--script``, ``--data``, ``filenames``.

* ``--script TEXT``: Python script to execute when the application starts.

  * Excludes: ``--script``, ``--data``, ``filenames``.

* ``--data TEXT ...``: Load the specified data file(s) when the client starts. For file series,
  replace the numeral with a dot (e.g., ``my0.vtk, my1.vtk...myN.vtk`` becomes ``my..vtk``).

  * Excludes: ``--state``, ``--script``, ``filenames``.

* ``--live INT``: Connect to Catalyst Live session at the specified port number. Default is ``-1``.

**Testing specific options**:

* ``--baseline-directory TEXT``: Directory where the test recorder will store baseline images.

  * Can also be set via the ``PARAVIEW_TEST_BASELINE_DIR`` environment variable.

* ``--test-directory TEXT``: Directory for temporary test results and files.

  * Can also be set via the ``PARAVIEW_TEST_DIR`` environment variable.

* ``--data-directory TEXT``: Directory containing input data files for tests.

  * Can also be set via the ``PARAVIEW_DATA_ROOT`` environment variable.

* ``--test-script TEXT ...``: Test scripts to execute, in the order specified on the command line.
* ``--test-baseline TEXT: ...``: Specify baseline for test scripts provided.
* ``--test-threshold FLOAT ...``: Test image comparison threshold for test scripts provided.
* ``--exit``: Exits application when tests are finished.

**Options affecting connections between client/server processes**:

* ``--url``, ``--server-url TEXT``: Specify the server connection URL. On startup, the client will
  connect to the server using the URL specified.

  * Excludes: ``--server``.

* ``-s``, ``--server TEXT``: Specify the server resource name for client connection.

  *  Excludes: ``--url``

* ``--servers-file TEXT ...``: Additional servers configuration file(s) (``.pvsc``) to use.
* ``--multi-servers``: (Experimental) Enables the client to connect to multiple independent servers
  at the same time.

.. _sec:pvpythonCommandLineArguments:

|pvpython|-Specific Options
===========================

**Connection options**: These are the same as the connection options in the :ref:`sec:paraviewCommandLineArguments`.

.. _sec:pvbatchCommandLineArguments:

|pvbatch|-Specific Options
==========================

**General options**:

* ``-s``, ``--sym``, ``--symmetric``: When specified, the python script is processed symmetrically
  on all processes.

.. _sec:pvserverCommandLineArguments:

|pvserver|-Specific Options
===========================

**Options affecting connections between client/server processes**:

* ``--client-host TEXT``: Specify the hostname for reverse-connection mode. Default is
  ``localhost``.
* ``-r``, ``--rc``, ``--reverse-connection``: Uses reverse connection mode, where instead of the
  client connecting to the server(s), the server(s) will connect back to the client. Default is ``0``.
* ``-p``, ``--sp``, ``--server-port INT``: Port number to use to listen for connections from the
  client. In reverse-connection mode, this is the port number on which the client is listening for
  connections. Default is ``11111``.
* ``--bind-address TEXT``: Specifies the address to bind the server socket to. Default is
  ``0.0.0.0``.
* ``--timeout INT``: Specifies the timeout in minutes for a server connection. Default is ``0``.
* ``--timeout-command TEXT``: Command for the server to periodically check remaining connection
  time. When executed, the command should write an integer value to stdout.
* ``--timeout-command-interval INT``: Interval in seconds between consecutive calls to the timeout
  command. Default is ``60``.

  * Needs: ``--timeout-command``.

**Tile-display specific options**:

* ``--tdx``, ``--tile-dimensions-x INT``: Number of displays in the horizontal direction.
* ``--tdy``, ``--tile-dimensions-y INT``: Number of displays in the vertical direction.
* ``--tmx``, ``--tile-mullion-x INT``: Size of the gap in pixels between displays in the horizontal
  direction.
* ``--tmy``, ``--tile-mullion-y INT``: Size of the gap in pixels between displays in the vertical
  direction.

**CAVE specific options**:

* ``--pvx TEXT``: ParaView CAVE configuration file (typically a ``.pvx`` file) that provides the
  configuration for screens in a CAVE.

.. _sec:pvdataserverCommandLineArguments:

|pvdataserver|-Specific Options
===============================

**Connection options**: These are the same as in :ref:`sec:pvserverCommandLineArguments`, except
that the ``-p, --sp, --server-port`` flag is replaced with:

* ``-p``, ``--dsp``, ``--data-server-port INT``: Port number to use to listen for connections from
  the client. In reverse-connection mode, this is the port number on which the client is listening
  for connections. Default is ``11111``.

.. _sec:pvrenderserverCommandLineArguments:

|pvrenderserver|-Specific Options
=================================

The **Tile Display**, **CAVE** and **Connection options** are the same as those in
:ref:`sec:pvserverCommandLineArguments`, except that the ``-p, --sp, --server-port`` connection
option is replaced with:

* ``-p``,  ``--rsp``, ``--render-server-port INT``: Port number to use to listen for connections
  from the client. In reverse-connection mode, this is the port number on which the client is
  listening for connections. Default is ``22221``.
