CLI Reference Guide¶
Complete command-line interface reference for the portfolio management toolkit.
This document is generated from the CLI scripts’ --help output so the flags, defaults, and descriptions always match the implementation. Run python scripts/generate_cli_docs.py (or python3.12 scripts/generate_cli_docs.py --python python3.12) to rebuild the fragments under docs/_includes/cli/, then update docs/CLI_REFERENCE.md and the include directory in the same commit.
Table of Contents¶
- prepare_tradeable_data.py
- select_assets.py
- classify_assets.py
- calculate_returns.py
- manage_universes.py
- construct_portfolio.py
- run_backtest.py
prepare_tradeable_data.py¶
Command: python scripts/prepare_tradeable_data.py
Synopsis¶
Options¶
[--metadata-output METADATA_OUTPUT]
[--force-reindex]
[--tradeable-dir TRADEABLE_DIR]
[--match-report MATCH_REPORT]
[--unmatched-report UNMATCHED_REPORT]
[--prices-output PRICES_OUTPUT]
[--log-level {DEBUG,INFO,WARNING,ERROR}]
[--overwrite-prices] [--include-empty-prices]
[--lse-currency-policy {broker,stooq,strict}]
[--max-workers MAX_WORKERS]
[--index-workers INDEX_WORKERS]
[--incremental]
[--cache-metadata CACHE_METADATA]
Prepare tradeable Stooq datasets.
options:
-h, --help show this help message and exit
--data-dir DATA_DIR Root directory containing unpacked Stooq data.
--metadata-output METADATA_OUTPUT
Path to write the Stooq metadata index CSV.
--force-reindex Rebuild the Stooq metadata index even if the CSV
already exists.
--tradeable-dir TRADEABLE_DIR
Directory containing tradeable instrument CSV files.
--match-report MATCH_REPORT
Output CSV for matched tradeable instruments.
--unmatched-report UNMATCHED_REPORT
Output CSV listing unmatched instruments.
--prices-output PRICES_OUTPUT
Directory for exported tradeable price histories.
--log-level {DEBUG,INFO,WARNING,ERROR}
Logging verbosity.
--overwrite-prices Rewrite price CSVs even if they already exist.
--include-empty-prices
Export price CSVs even when the source file lacks
usable data.
--lse-currency-policy {broker,stooq,strict}
How to resolve LSE currency mismatches.
--max-workers MAX_WORKERS
Maximum number of threads to use for matching and
exporting (auto if unset).
--index-workers INDEX_WORKERS
Number of threads for directory indexing (0 falls back
to --max-workers).
--incremental Enable incremental resume: skip processing if inputs
unchanged and outputs exist.
--cache-metadata CACHE_METADATA
Path to cache metadata file for incremental resume.
select_assets.py¶
Command: python scripts/select_assets.py
Synopsis¶
Options¶
[--data-status DATA_STATUS]
[--min-history-days MIN_HISTORY_DAYS]
[--min-price-rows MIN_PRICE_ROWS]
[--max-gap-days MAX_GAP_DAYS] [--severity SEVERITY]
[--markets MARKETS] [--regions REGIONS]
[--currencies CURRENCIES] [--allowlist ALLOWLIST]
[--blocklist BLOCKLIST] [--verbose] [--dry-run]
[--chunk-size CHUNK_SIZE]
Asset Selection CLI
options:
-h, --help show this help message and exit
--match-report MATCH_REPORT
Path to the tradeable matches CSV file.
--output OUTPUT Output path for the selected assets CSV. Prints to
stdout if not specified.
--data-status DATA_STATUS
Comma-separated list of acceptable data statuses
(e.g., "ok,warning").
--min-history-days MIN_HISTORY_DAYS
Minimum required days of price history.
--min-price-rows MIN_PRICE_ROWS
Minimum required number of price rows.
--max-gap-days MAX_GAP_DAYS
Maximum allowed gap in days between consecutive
prices.
--severity SEVERITY Comma-separated list of zero-volume severity levels to
include.
--markets MARKETS Comma-separated list of markets to include.
--regions REGIONS Comma-separated list of regions to include.
--currencies CURRENCIES
Comma-separated list of currencies to include.
--allowlist ALLOWLIST
Path to a file with symbols/ISINs to allow (one per
line).
--blocklist BLOCKLIST
Path to a file with symbols/ISINs to block (one per
line).
--verbose Enable detailed logging.
--dry-run Show what would be selected without performing the
action.
--chunk-size CHUNK_SIZE
Enable streaming mode with specified chunk size (e.g.,
5000). If not specified, loads entire file into memory
(default behavior).
classify_assets.py¶
Command: python scripts/classify_assets.py
Synopsis¶
Options¶
[--overrides OVERRIDES]
[--export-for-review EXPORT_FOR_REVIEW] [--summary]
[--verbose]
Asset Classification CLI
options:
-h, --help show this help message and exit
--input INPUT Path to the selected assets CSV file.
--output OUTPUT Output path for the classified assets CSV. Prints to
stdout if not specified.
--overrides OVERRIDES
Path to a CSV file with classification overrides.
--export-for-review EXPORT_FOR_REVIEW
Export a template for manual review.
--summary Print a summary of the classification results.
--verbose Enable detailed logging.
calculate_returns.py¶
Command: python scripts/calculate_returns.py
Synopsis¶
Options¶
[--output OUTPUT] [--method {simple,log,excess}]
[--frequency {daily,weekly,monthly}]
[--risk-free-rate RISK_FREE_RATE]
[--handle-missing {forward_fill,drop,interpolate}]
[--max-forward-fill MAX_FORWARD_FILL]
[--min-periods MIN_PERIODS]
[--loader-workers LOADER_WORKERS]
[--cache-size CACHE_SIZE]
[--io-backend {pandas,polars,pyarrow,auto}]
[--align-method {outer,inner}] [--business-days]
[--min-coverage MIN_COVERAGE] [--summary]
[--top TOP] [--verbose]
Prepare aligned return series for selected assets
options:
-h, --help show this help message and exit
--assets ASSETS Path to selected assets CSV file
--prices-dir PRICES_DIR
Directory containing price files
--output OUTPUT Destination CSV for prepared returns
--method {simple,log,excess}
Return calculation method
--frequency {daily,weekly,monthly}
Frequency for the prepared returns
--risk-free-rate RISK_FREE_RATE
Annual risk-free rate used for excess returns
--handle-missing {forward_fill,drop,interpolate}
Missing data strategy
--max-forward-fill MAX_FORWARD_FILL
Maximum consecutive days to forward-fill or
interpolate
--min-periods MIN_PERIODS
Minimum number of price observations required per
asset
--loader-workers LOADER_WORKERS
Maximum worker threads for price loading (default:
auto)
--cache-size CACHE_SIZE
Maximum number of price series to cache (default:
1000, 0 to disable)
--io-backend {pandas,polars,pyarrow,auto}
IO backend for CSV reading (default: pandas). Options:
pandas (default), polars (fast), pyarrow (fast), auto
(select best available)
--align-method {outer,inner}
How to align return date indexes before resampling
--business-days Reindex returns to the business-day calendar before
coverage filtering
--min-coverage MIN_COVERAGE
Minimum proportion of non-NaN returns required per
asset
--summary Print a textual summary instead of raw returns
--top TOP Number of top/bottom assets to display in the summary
--verbose Enable debug logging
manage_universes.py¶
Command: python scripts/manage_universes.py
Synopsis¶
Options¶
[--prices-dir PRICES_DIR] [--verbose]
{list,show,load,compare,validate,validate-file,compare-files}
...
Universe Management CLI
positional arguments:
{list,show,load,compare,validate,validate-file,compare-files}
list List available universes (legacy).
show Show details for a universe (legacy).
load Load and export a universe (legacy).
compare Compare universes (legacy).
validate Validate a universe (legacy).
validate-file Validate a universe configuration file.
compare-files Compare two universe configuration files.
options:
-h, --help show this help message and exit
--config CONFIG Path to the universe config file.
--matches MATCHES Path to the tradeable matches CSV file.
--prices-dir PRICES_DIR
Directory with price files.
--verbose Enable detailed logging.
construct_portfolio.py¶
Command: python scripts/construct_portfolio.py
Synopsis¶
Options¶
[--classifications CLASSIFICATIONS]
[--strategy STRATEGY] [--compare]
[--max-weight MAX_WEIGHT]
[--min-weight MIN_WEIGHT]
[--max-equity MAX_EQUITY] [--min-bond MIN_BOND]
[--verbose]
Construct and compare portfolio strategies.
options:
-h, --help show this help message and exit
--returns RETURNS Path to CSV containing asset returns (dates as index,
tickers as columns).
--output OUTPUT Path to write the resulting weights (or comparison
table when --compare is enabled).
--classifications CLASSIFICATIONS
Optional CSV with columns 'ticker' and 'asset_class'
for constraint enforcement.
--strategy STRATEGY Strategy name to construct (ignored when --compare is
provided).
--compare Compare all registered strategies instead of
constructing a single one.
--max-weight MAX_WEIGHT
Maximum allowable weight for any asset (default:
0.25).
--min-weight MIN_WEIGHT
Minimum allowable weight for any asset (default: 0.0).
--max-equity MAX_EQUITY
Maximum total equity exposure (default: 0.90).
--min-bond MIN_BOND Minimum total bond/cash exposure (default: 0.10).
--verbose Enable verbose logging output.
Portfolio construction command-line interface.
Usage examples:
python scripts/construct_portfolio.py --returns data/processed/universe_returns.csv --strategy equal_weight --output outputs/portfolio_equal_weight.csv
python scripts/construct_portfolio.py --returns data/processed/universe_returns.csv --classifications data/processed/asset_classes.csv --strategy mean_variance_max_sharpe --max-equity 0.80 --output outputs/portfolio_mv.csv
python scripts/construct_portfolio.py --returns data/processed/universe_returns.csv --compare --output outputs/portfolio_comparison.csv
run_backtest.py¶
Command: python scripts/run_backtest.py
Synopsis¶
Options¶
[--initial-capital INITIAL_CAPITAL]
[--commission COMMISSION] [--slippage SLIPPAGE]
[--min-commission MIN_COMMISSION]
[--rebalance-frequency {daily,weekly,monthly,quarterly,annual}]
[--drift-threshold DRIFT_THRESHOLD]
[--lookback-periods LOOKBACK_PERIODS]
[--universe-file UNIVERSE_FILE]
[--universe-name UNIVERSE_NAME]
[--prices-file PRICES_FILE]
[--returns-file RETURNS_FILE]
[--max-position-size MAX_POSITION_SIZE]
[--min-position-size MIN_POSITION_SIZE]
[--target-return TARGET_RETURN]
[--risk-aversion RISK_AVERSION]
[--preselect-method {momentum,low_vol,combined}]
[--preselect-top-k PRESELECT_TOP_K]
[--preselect-lookback PRESELECT_LOOKBACK]
[--preselect-skip PRESELECT_SKIP]
[--preselect-momentum-weight PRESELECT_MOMENTUM_WEIGHT]
[--preselect-low-vol-weight PRESELECT_LOW_VOL_WEIGHT]
[--enable-indicators] [--indicator-provider {noop}]
[--membership-enabled]
[--membership-buffer-rank MEMBERSHIP_BUFFER_RANK]
[--membership-min-hold MEMBERSHIP_MIN_HOLD]
[--membership-max-turnover MEMBERSHIP_MAX_TURNOVER]
[--membership-max-new MEMBERSHIP_MAX_NEW]
[--membership-max-removed MEMBERSHIP_MAX_REMOVED]
[--use-pit-eligibility]
[--min-history-days MIN_HISTORY_DAYS]
[--min-price-rows MIN_PRICE_ROWS] [--enable-cache]
[--cache-dir CACHE_DIR]
[--cache-max-age-days CACHE_MAX_AGE_DAYS]
[--output-dir OUTPUT_DIR] [--no-visualize]
[--save-trades] [--verbose] [--strict]
[--ignore-warnings] [--show-defaults]
{equal_weight,risk_parity,mean_variance}
Run portfolio backtest with specified strategy and parameters.
positional arguments:
{equal_weight,risk_parity,mean_variance}
Portfolio construction strategy to use
options:
-h, --help show this help message and exit
--start-date START_DATE
Backtest start date (YYYY-MM-DD). Default: 2020-01-01
--end-date END_DATE Backtest end date (YYYY-MM-DD). Default: today
--initial-capital INITIAL_CAPITAL
Initial portfolio capital. Default: 100000
--commission COMMISSION
Commission rate (e.g., 0.001 = 0.1%). Default: 0.001
--slippage SLIPPAGE Slippage rate (e.g., 0.0005 = 0.05%). Default: 0.0005
--min-commission MIN_COMMISSION
Minimum commission per trade. Default: 1.0
--rebalance-frequency {daily,weekly,monthly,quarterly,annual}
Rebalancing frequency. Default: monthly
--drift-threshold DRIFT_THRESHOLD
Drift threshold for opportunistic rebalancing (e.g.,
0.05 = 5%). Default: 0.05
--lookback-periods LOOKBACK_PERIODS
Rolling lookback window for parameter estimation
(days). Default: 252 (1 year)
--universe-file UNIVERSE_FILE
Path to universe configuration file. Default:
config/universes.yaml
--universe-name UNIVERSE_NAME
Universe name in configuration file. Default: default
--prices-file PRICES_FILE
Path to prices CSV file. Default:
data/processed/prices.csv
--returns-file RETURNS_FILE
Path to returns CSV file. Default:
data/processed/returns.csv
--max-position-size MAX_POSITION_SIZE
Maximum position size (0-1). Default: 0.25
--min-position-size MIN_POSITION_SIZE
Minimum position size (0-1). Default: 0.01
--target-return TARGET_RETURN
Target return for mean-variance strategy (annualized)
--risk-aversion RISK_AVERSION
Risk aversion parameter for mean-variance (higher =
more conservative). Default: 1.0
--preselect-method {momentum,low_vol,combined}
Preselection method (momentum, low_vol, or combined)
--preselect-top-k PRESELECT_TOP_K
Number of assets to select via preselection (0 or None
to disable)
--preselect-lookback PRESELECT_LOOKBACK
Lookback period for preselection factors (days).
Default: 252
--preselect-skip PRESELECT_SKIP
Skip most recent N days for momentum calculation.
Default: 1
--preselect-momentum-weight PRESELECT_MOMENTUM_WEIGHT
Weight for momentum in combined preselection (0-1).
Default: 0.5
--preselect-low-vol-weight PRESELECT_LOW_VOL_WEIGHT
Weight for low-volatility in combined preselection
(0-1). Default: 0.5
--enable-indicators Enable technical indicator filtering (currently no-op
stub)
--indicator-provider {noop}
Indicator provider to use. Default: noop (currently
only option)
--membership-enabled Enable membership policy to control asset churn during
rebalancing
--membership-buffer-rank MEMBERSHIP_BUFFER_RANK
Rank buffer to protect existing holdings (higher =
more stable). Default: 5
--membership-min-hold MEMBERSHIP_MIN_HOLD
Minimum rebalance periods to hold an asset. Default: 3
--membership-max-turnover MEMBERSHIP_MAX_TURNOVER
Maximum portfolio turnover per rebalancing (0-1, e.g.,
0.3 = 30%)
--membership-max-new MEMBERSHIP_MAX_NEW
Maximum number of new assets to add per rebalancing
--membership-max-removed MEMBERSHIP_MAX_REMOVED
Maximum number of assets to remove per rebalancing
--use-pit-eligibility
Enable point-in-time eligibility filtering to avoid
lookahead bias
--min-history-days MIN_HISTORY_DAYS
Minimum days of history for PIT eligibility (default:
252 = 1 year)
--min-price-rows MIN_PRICE_ROWS
Minimum price rows for PIT eligibility (default: 252)
--enable-cache Enable on-disk caching for factor scores and PIT
eligibility
--cache-dir CACHE_DIR
Directory for cache storage. Default: .cache/backtest
--cache-max-age-days CACHE_MAX_AGE_DAYS
Maximum age of cache entries in days (optional, no
limit if not set)
--output-dir OUTPUT_DIR
Output directory for results. Default:
results/backtest_TIMESTAMP
--no-visualize Skip generating visualization data files
--save-trades Save detailed trade history to CSV
--verbose Print detailed progress information
--strict Treat configuration warnings as errors (strict
validation mode)
--ignore-warnings Suppress configuration warnings (not recommended)
--show-defaults Display sensible default values and exit
Backtest CLI - Command-line interface for running portfolio backtests.
This script provides a user-friendly interface for executing backtests with
configurable parameters including strategy selection, date ranges, transaction
costs, and output options.
Examples:
# Run equal-weight strategy with default settings
python scripts/run_backtest.py equal_weight
# Run risk parity with custom date range and costs
python scripts/run_backtest.py risk_parity \\
--start-date 2020-01-01 \\
--end-date 2023-12-31 \\
--commission 0.001 \\
--slippage 0.0005
# Run mean-variance with monthly rebalancing and save output
python scripts/run_backtest.py mean_variance \\
--rebalance-frequency monthly \\
--output-dir results/backtest_2024
# Run with custom universe and no visualization
python scripts/run_backtest.py equal_weight \\
--universe-file config/custom_universe.yaml \\
--no-visualize