CLI¶
Command-line interface for running backtests and managing configurations.
Entry Point
sf -- Installed automatically with the package via pip install signalflow-trading.
Commands¶
sf run¶
Run a backtest from a YAML configuration file.
sf run config.yaml # Run backtest
sf run config.yaml -o results.json # Save results to JSON
sf run config.yaml --plot --quiet # Show plots, suppress output
sf init¶
Create a sample YAML configuration file in the current directory.
sf validate¶
Validate a configuration file without running the backtest.
sf list¶
List available components registered in the SignalFlow registry.
sf list detectors # List all detectors
sf list metrics # List all metrics
sf list features # List all features
sf list all # List everything
YAML Configuration¶
Basic Example¶
strategy:
name: sma_crossover
data:
source: data/binance.duckdb
pairs: [BTCUSDT, ETHUSDT]
start: "2024-01-01"
end: "2024-06-01"
timeframe: 1h
detector:
name: example/sma_cross
params:
fast_period: 20
slow_period: 50
entry:
size_pct: 0.1
exit:
tp: 0.03
sl: 0.015
capital: 50000
Multi-Component Example¶
strategy:
name: ensemble
data:
spot_1m:
source: data/binance.duckdb
pairs: [BTCUSDT, ETHUSDT]
start: "2024-01-01"
timeframe: 1m
detectors:
fast_sma:
name: example/sma_cross
params:
fast_period: 5
slow_period: 15
slow_sma:
name: example/sma_cross
params:
fast_period: 20
slow_period: 50
aggregation:
mode: weighted
weights: [0.6, 0.4]
entries:
aggressive:
source_detector: fast_sma
size_pct: 0.05
conservative:
source_detector: slow_sma
size_pct: 0.15
exits:
tight:
tp: 0.02
sl: 0.01
trailing:
trailing: 0.03
capital: 50000
API Reference¶
signalflow.cli.config.BacktestConfig
dataclass
¶
BacktestConfig(strategy_id: str = 'backtest', data: DataConfig | None = None, detector: DetectorConfig | None = None, entry: EntryConfig = EntryConfig(), exit: ExitConfig = ExitConfig(), data_sources: dict[str, DataConfig] | None = None, detectors: dict[str, DetectorConfig] | None = None, validators: dict[str, ValidatorConfig] | None = None, entries: dict[str, EntryConfig] | None = None, exits: dict[str, ExitConfig] | None = None, aggregation: AggregationConfig | None = None, capital: float = 10000.0, fee: float = 0.001, show_progress: bool = True)
Complete backtest configuration from YAML.
Supports both singular (backward compatible) and plural keys:
- data / data_sources
- detector / detectors
- entry / entries
- exit / exits
Example YAML (single):
strategy:
id: my_strategy
data:
source: data/binance.duckdb
pairs: [BTCUSDT]
start: "2024-01-01"
detector:
name: example/sma_cross
params: {fast_period: 20, slow_period: 50}
entry:
size_pct: 0.1
exit:
tp: 0.03
sl: 0.015
capital: 50000
Example YAML (multi-component):
strategy:
id: ensemble
data_sources:
spot_1m:
source: data/binance.duckdb
pairs: [BTCUSDT]
start: "2024-01-01"
timeframe: 1m
spot_1h:
source: data/binance.duckdb
pairs: [BTCUSDT]
start: "2024-01-01"
timeframe: 1h
detectors:
trend:
name: example/sma_cross
params: {fast_period: 20, slow_period: 50}
data_source: spot_1h
volume:
name: example/volume_spike
params: {threshold: 2.0}
data_source: spot_1m
aggregation:
mode: weighted
weights: [0.7, 0.3]
entries:
trend_entry:
size_pct: 0.15
source_detector: trend
volume_entry:
size_pct: 0.05
source_detector: volume
exits:
standard:
tp: 0.03
sl: 0.015
trailing:
trailing: 0.02
capital: 50000
validators
class-attribute
instance-attribute
¶
_parse_named_data
staticmethod
¶
Parse named data configs from dict or list format.
_parse_named_detectors
staticmethod
¶
Parse named detector configs from dict or list format.
_parse_named_entries
staticmethod
¶
Parse named entry configs from dict or list format.
_parse_named_exits
staticmethod
¶
Parse named exit configs from dict or list format.
_parse_named_validators
staticmethod
¶
Parse named validator configs from dict or list format.
from_dict
classmethod
¶
Create config from dictionary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
d
|
dict[str, Any]
|
Configuration dictionary |
required |
Returns:
| Type | Description |
|---|---|
BacktestConfig
|
BacktestConfig instance |
from_yaml
classmethod
¶
Load configuration from YAML file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | Path
|
Path to YAML config file |
required |
Returns:
| Type | Description |
|---|---|
BacktestConfig
|
BacktestConfig instance |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If file doesn't exist |
ValueError
|
If config is invalid |
to_builder ¶
Convert config to BacktestBuilder.
Returns:
| Type | Description |
|---|---|
Any
|
Configured BacktestBuilder instance |
validate ¶
Validate configuration and return list of issues.
Returns:
| Type | Description |
|---|---|
list[str]
|
List of error/warning messages |
signalflow.cli.config.DataConfig
dataclass
¶
DataConfig(source: str, pairs: list[str], start: str | datetime, end: str | datetime | None = None, timeframe: str = '1m', data_type: str = 'perpetual')
Data source configuration.
signalflow.cli.config.DetectorConfig
dataclass
¶
Detector configuration.
signalflow.cli.config.EntryConfig
dataclass
¶
EntryConfig(rule: str | None = None, size: float | None = None, size_pct: float | None = None, max_positions: int = 10, max_per_pair: int = 1, source_detector: str | None = None)
Entry rules configuration.
signalflow.cli.config.ExitConfig
dataclass
¶
ExitConfig(rule: str | None = None, tp: float | None = None, sl: float | None = None, trailing: float | None = None, time_limit: int | None = None)
Exit rules configuration.