.. _CLI_Documentation:

CLI Documentation
=================

The Backtest Engine ships with a command-line interface that handles
the full project lifecycle — scaffolding a new project, executing
backtests, and refreshing template files after a package upgrade. It
is the recommended entry point for end users who configure backtests
through Excel and run them from a terminal.

If you are setting up the engine for the first time, follow
:ref:`quick_start` for an end-to-end walkthrough. The CLI is invoked
as a module:

.. code-block:: console

    python -m kaxanuk.backtest_engine <command> [options]

Command summary
---------------

.. list-table::
   :header-rows: 1
   :widths: 15 85

   * - Command
     - Purpose
   * - ``autorun``
     - Install the project files on first run, otherwise execute the
       existing entry script. Convenience shortcut combining ``init``
       and ``run``.
   * - ``init``
     - Create the directory layout (``Config/``, ``Input/Data/``,
       ``Input/Portfolios/``, ``Output/``) and copy the Excel
       parameters template plus a default ``__main__.py``.
   * - ``run``
     - Execute one or more entry scripts. Without arguments, runs the
       ``__main__.py`` in the current directory.
   * - ``update``
     - Regenerate the Excel parameters template or the entry script
       in an existing project. Used after upgrading the package.

Common workflows
----------------

First-time setup
~~~~~~~~~~~~~~~~

Create a new project, populate the input folders, and run a backtest:

.. code-block:: console

    # 1. Scaffold the project structure
    python -m kaxanuk.backtest_engine init excel

    # 2. Configure the run
    #    - Edit Config/backtest_engine_parameters.xlsx
    #    - Drop your market data files into Input/Data/
    #    - Drop your portfolio definition into Input/Portfolios/

    # 3. Execute the backtest
    python -m kaxanuk.backtest_engine run

Refer to :ref:`data_formats` for the exact column layout expected by
the input files, and to :ref:`configuration` for the meaning of each
parameter in the Excel workbook.

One-shot autorun
~~~~~~~~~~~~~~~~

``autorun`` collapses install and execute into a single command. The
first invocation installs the files; the second one (after you have
filled in the Excel template) executes the backtest:

.. code-block:: console

    python -m kaxanuk.backtest_engine autorun

Run several projects at once
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``run`` accepts a variadic list of paths to entry scripts or
directories. Useful for batch comparison across strategies or
configurations:

.. code-block:: console

    python -m kaxanuk.backtest_engine run ./momentum ./value ./mean_reversion

Updating the templates after a package upgrade
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When a new release ships an updated Excel template or entry script,
``update`` regenerates them in place. Existing files are renamed (for
example ``backtest_engine_parameters.1.xlsx``) so your local edits
remain available for reference:

.. code-block:: console

    python -m kaxanuk.backtest_engine update excel
    python -m kaxanuk.backtest_engine update entry_script

Command reference
-----------------

The block below is generated automatically from the ``click``
decorators and is kept in sync with the source code.

.. click:: kaxanuk.backtest_engine.services.cli:cli
   :prog: kaxanuk.backtest_engine
   :show-nested:

Technical reference
-------------------

.. automodule:: kaxanuk.backtest_engine.services.cli
   :members:
   :undoc-members:
   :show-inheritance:
   :member-order: bysource