The run Command

The run command executes a strategy backtest. This chapter provides a comprehensive guide to all available options.

Basic usage

algo run --strategy <name> --symbols <symbols> [flags]

At minimum, a strategy and at least one symbol must be specified.

Date range

Flag	Default	Description
`--date-from`	`2010-01-01`	Start date (YYYY-MM-DD)
`--date-to`	Today	End date (YYYY-MM-DD)
`--use-first N`		Use only the first N% of data (in-sample)
`--use-last N`		Use only the last N% of data (out-of-sample)

algo run --strategy kbt --symbols @ES --date-from 2015-01-01 --date-to 2024-12-31

The --use-first and --use-last flags are useful for dividing data into in-sample and out-of-sample periods:

# Train on first 70%
algo run --strategy kbt --symbols @ES --use-first 70

# Test on last 30%
algo run --strategy kbt --symbols @ES --use-last 30

Bar configuration

Flag	Default	Description
`--bar-interval`	`daily`	Bar size: `daily`, `weekly`, `monthly`, `Nm`, `Nh`
`--bar-building-mode`	`natural`	`natural` or `session`
`--max-bars-back`	`263`	Maximum lookback period
`--no-look-inside-bar`	`false`	Disable intra-bar order evaluation
`--bouncing-ticks`	`0`	Bouncing ticks percentage (0-100)

Session configuration

Flag	Default	Description
`--session-hours`	Symbol default	Trading hours (e.g., `9:30am-4:00pm`)
`--session-days`	Symbol default	Trading days (e.g., `Mon-Fri`)
`--timezone`	Exchange timezone	IANA timezone (e.g., `America/New_York`)
`--no-out-of-session-execution`	`false`	Disable shadow bar processing

Cost model

Slippage

Flag	Default	Description
`--slippage-mode`	`per-unit`	`per-unit` or `per-trade`
`--slippage-ticks`	`0`	Number of ticks of slippage

Commission

Flag	Default	Description
`--commission-mode`	`per-unit`	`per-unit`, `per-trade`, or `percentage`
`--commission-amount`	`0`	Commission amount (supports currency: `2.50USD`)
`--commission-percentage`	`0`	Commission as percentage of trade value

Capital and position sizing

Flag	Default	Description
`--initial-capital`	`1000000`	Starting capital (supports formats: `USD100000`, `100,000 USD`)
`--position-size`	`1`	Default contracts/shares per trade
`--risk-free-rate`	`0.04`	Annual risk-free rate for Sharpe calculation

Direction control

Flag	Default	Description
`--dir-long-only`	`false`	Allow only long positions
`--dir-short-only`	`false`	Allow only short positions
`--no-pyramiding`	`true`	Disable pyramiding

Strategy inputs

Override strategy input defaults from the command line:

algo run --strategy macrossover --symbols @ES --inputs LenFast=5,LenSlow=50

Multiple inputs are comma-separated. Values must match the type of the corresponding struct field.

Data detrending

Apply logarithmic detrending to remove trend bias:

algo run --strategy kbt --symbols @ES --detrend 0 --detrend-mode simple

The --detrend argument specifies which data series indices to detrend (0-based). The mode can be simple or regression.

Parallel execution

When running multiple symbols, use --parallel to run them concurrently:

algo run --strategy kbt --symbols @ES,@NQ,@GC,@CL --parallel 8

The default is 64 workers. Use --parallel 0 for sequential execution.

Symbol specification

The --symbols flag supports flexible syntax. The / separator has higher precedence than ,: slashes divide the expression into positional legs (Data0, Data1, etc.), while commas list alternatives within each leg. The cartesian product of all legs produces the final set of runs.

Syntax	Meaning	Runs
`@ES`	Single symbol	1 run
`@ES,@NQ`	Comma-separated alternatives	2 runs (one per symbol)
`@ES/@NQ`	Two legs, one symbol each	1 run with 2 data series
`@ES,@NQ/@GC`	Two legs, first has 2 alternatives	2 runs (`@ES/@GC`, `@NQ/@GC`)
`<metals`	Portfolio reference	1 run per symbol in the file
`<metals/@NQ`	Portfolio × symbol	5 runs (each metal paired with @NQ)
`<metals/<softs`	Portfolio × portfolio	40 runs (5 metals × 8 softs)
`@ES,@NQ,@YM/<metals`	3 alternatives × 5 metals	15 runs
`@ES/[@GC,@HG,@PA]`	Bracket group (see below)	1 run with 4 data series
`@ES,@NQ/[<metals]`	Alternatives × bracket group	2 runs (each primary with all metals)

Bracket grouping

Square brackets [...] group symbols into a single entity that is passed to the strategy as a whole, rather than being expanded via cartesian product. All symbols inside the brackets become consecutive data series (Data1, Data2, etc.) within a single run.

# Without brackets: 15 runs (3 × 5 cartesian product, each a 2-series run)
algo run --strategy spread --symbols @ES,@NQ,@YM/<metals

# With brackets: 3 runs (each primary symbol gets ALL metals as Data1-Data5)
algo run --strategy multisymbol --symbols @ES,@NQ,@YM/[<metals]

Portfolio references work inside brackets:

# Each soft commodity gets all metals as a group (8 runs, each with 6 data series)
algo run --strategy multisymbol --symbols <softs/[<metals]

# Each soft commodity gets all softs as a group, including itself (8 runs)
algo run --strategy multisymbol --symbols <softs/[<softs]

Brackets on the primary (Data0) position never make sense, since primary symbols are always processed one at a time. Use brackets only on non-primary legs.

Bar intervals with grouped symbols

When using bracket groups, the --bar-interval flag follows these rules:

Intervals provided	Behaviour
1 (`daily`)	All data series use the same interval
2 (`daily/weekly`)	Data0 uses the first, all others use the second
N (matching symbol count)	Each data series uses the corresponding interval

# All 6 series use daily bars
algo run --strategy ms --symbols @ES/[@GC,@HG,@PA,@PL,@SI] --bar-interval daily

# Data0 (@ES) uses daily, Data1-5 (metals) all use weekly
algo run --strategy ms --symbols @ES/[@GC,@HG,@PA,@PL,@SI] --bar-interval daily/weekly

If more than two bar intervals are provided, the count must exactly match the number of symbols in the run.

Output and Reporting