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 Quick Start Guide for an end-to-end walkthrough. The CLI is invoked as a module:
python -m kaxanuk.backtest_engine <command> [options]
Command summary#
Command |
Purpose |
|---|---|
|
Install the project files on first run, otherwise execute the
existing entry script. Convenience shortcut combining |
|
Create the directory layout ( |
|
Execute one or more entry scripts. Without arguments, runs the
|
|
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:
# 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 Data Formats for the exact column layout expected by the input files, and to Configuration Reference 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:
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:
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:
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.
kaxanuk.backtest_engine#
Backtest Engine command-line interface.
Provides four subcommands to manage a backtest project end-to-end:
Run a subcommand with –help to see its specific options.
Usage
kaxanuk.backtest_engine [OPTIONS] COMMAND [ARGS]...
Options
- --version#
Show the version and exit.
autorun#
Install missing files on first run, then execute the entry script.
Convenience command for end users: when the current directory does
not contain a __main__.py entry script, autorun installs
the Excel project structure (Config/, Input/Data/, Input/Portfolios/,
Output/) plus a default __main__.py and exits, asking you to
fill in the configuration. On a subsequent invocation, when the
entry script is already present, autorun runs it instead.
Typical first-time flow:
Usage
kaxanuk.backtest_engine autorun [OPTIONS]
init#
Create the directories and template files for a backtest project.
CONFIG_FORMAT is the configuration format to initialize. Currently
only excel is supported, which lays out the project around an
Excel parameters workbook.
The command creates the following structure in the current working directory:
The --entry_script option lets you customize the name of the
generated entry script (useful when you want to keep several
projects side by side).
If a Config/ directory already exists, the command refuses to
overwrite it and asks you to run update instead.
Parameters#
- config_format
The name of the configuration format to be initialized
- entry_script
The name of the entry script that will be generated
Usage
kaxanuk.backtest_engine init [OPTIONS] {excel}
Options
- --entry_script <entry_script>#
The name of the entry script that will be generated. Default: __main__.py
Arguments
- CONFIG_FORMAT#
Required argument
run#
Execute one or more backtest entry scripts.
ENTRY_SCRIPT_LOCATIONS is a variadic list of paths to Python entry
scripts (or to directories containing a __main__.py) that will
be executed in order. Each script runs as a separate subprocess
using the current Python interpreter.
With no argument, run looks for __main__.py in the current
working directory and executes that single script — equivalent to
the executing half of autorun.
Typical usage:
Parameters#
- entry_script_locations
The locations of the entry scripts that will be executed
Usage
kaxanuk.backtest_engine run [OPTIONS] [ENTRY_SCRIPT_LOCATIONS]...
Arguments
- ENTRY_SCRIPT_LOCATIONS#
Optional argument(s)
update#
Regenerate template files in an existing project.
CONFIG_FORMAT selects which template to refresh:
Existing files are not deleted: if a target file already exists,
it is renamed (.1.xlsx, .2.xlsx, …) before the new
template is written, so any local edits remain available.
Use this command after upgrading the package version to pick up
template changes shipped in the new release. For a brand-new
project, use init instead.
Parameters#
- config_format
The name of the configuration format to be reinitialized
Usage
kaxanuk.backtest_engine update [OPTIONS] {excel|entry_script}
Arguments
- CONFIG_FORMAT#
Required argument
Technical reference#
The cli entry points are defined and implemented here.