Command-Line Interface
======================

pyX2Cscope can be launched from the terminal with arguments that control which
GUI is started, which ELF file is loaded, and how the connection is
established.  Providing ``-e`` and ``-p`` at launch skips all manual input —
the application loads the ELF and connects to the target immediately.

.. code-block:: console

   python -m pyx2cscope [options]        # when installed with pip
   pyX2Cscope.exe [options]              # standalone executable

Quick reference
---------------

.. list-table::
   :widths: 22 12 66
   :header-rows: 1

   * - Argument
     - Short
     - Description
   * - ``--elf <path>``
     - ``-e``
     - Path to the ELF file generated by the firmware build.
       Required to load variable information.  If omitted, pyX2Cscope looks
       for a path stored in ``config.ini``.
   * - ``--port <port>``
     - ``-p``
     - Serial port to connect to (e.g. ``COM3``, ``/dev/ttyUSB0``).
       Use ``AUTO`` to scan for the first available LNet device automatically.
   * - ``--web``
     - ``-w``
     - Start the Web GUI instead of the Qt GUI.
   * - ``--qt``
     - ``-q``
     - Explicitly start the Qt GUI (default when ``-w`` is not given).
   * - ``--web-port <port>``
     - ``-wp``
     - TCP port for the web server (default: ``5000``).
       Only used with ``-w``.
   * - ``--host <host>``
     - —
     - Host address for the web server (default: ``localhost``).
       Set to ``0.0.0.0`` to allow connections from other devices on the
       network.  Only used with ``-w``.
   * - ``--log-level <level>``
     - ``-l``
     - Logging verbosity.  One of ``DEBUG``, ``INFO``, ``WARNING``,
       ``ERROR`` (default), ``CRITICAL``.
   * - ``--log-console``
     - ``-c``
     - Print log output to the terminal in addition to the log file.
   * - ``--install <pkg> …``
     - —
     - *Standalone executable only.* Install one or more Python packages
       into the ``libs/`` folder using the bundled interpreter.
       See :ref:`installing-extra-libraries`.
   * - ``--version``
     - ``-v``
     - Print the version number and exit.
   * - ``--help``
     - ``-h``
     - Print the full help message and exit.

Examples
--------

Start the Qt GUI, load an ELF, and auto-connect:

.. code-block:: console

   pyX2Cscope.exe -e firmware.elf -p AUTO

Start the Web GUI on the default port:

.. code-block:: console

   pyX2Cscope.exe -e firmware.elf -p COM3 -w

Start the Web GUI and allow access from other devices on the network:

.. code-block:: console

   pyX2Cscope.exe -e firmware.elf -w --host 0.0.0.0 -wp 8080

Run with verbose logging to the terminal:

.. code-block:: console

   pyX2Cscope.exe -e firmware.elf -l DEBUG -c

Install an extra library into the standalone executable:

.. code-block:: console

   pyX2Cscope.exe --install scipy

.. _installing-extra-libraries:

Installing extra libraries (standalone executable)
--------------------------------------------------

The standalone ``pyX2Cscope.exe`` ships with a bundled Python interpreter and
a fixed set of packages.  If your firmware uses a communication layer or
post-processing routine that requires an additional package (e.g. ``scipy``,
``pandas``), you can install it into the ``libs/`` folder that sits next to the
executable:

.. code-block:: console

   pyX2Cscope.exe --install scipy
   pyX2Cscope.exe --install scipy pandas   # multiple packages at once

The packages are installed via the bundled ``pip`` and are isolated from your
system Python.  They persist across restarts of the executable.