CLI and file reference
algo run flags
Single-run mode (mutually exclusive with --config):
| Flag | Default | Meaning |
|---|---|---|
--adapter PATH | (required) | Data adapter binary. |
--adapter-inputs k=v[,k=v...] | Adapter inputs (e.g. Path=...). | |
--data-protocol | auto | Data wire: auto, dbn, pb, csv. |
--strategy PATH | (required*) | Strategy binary. *Optional with --schema TRADES. |
--strategy-protocol | auto | Strategy wire: auto, pb, csv. Under --lifetime v2, auto offers stdio-csv-v2 between pb and CSV v1, and csv offers stdio-csv-v2 ahead of CSV v1 (see Negotiating stdio-csv-v2). |
--inputs k=v[,k=v...] | Strategy input values. | |
--symbols A[,B...] | (required) | Symbols; ONE instance receives every symbol’s series. |
--symbol SYM | Deprecated single-symbol alias for --symbols. | |
--session | empty | Trading-day container (eth, rth, or session) for 1d/1w time bars, or a custom exchange-local window custom:HHMM-HHMM for 1d bars (see Custom session windows), or an intraday grid boundary (utc-day, eth, rth, or session) with an intraday interval. A continuous run accepts the trading-day container at 1d/1w (it reads the feed’s session composite, eth when none is given; see --continuous-clock) and refuses the intraday grid; its symbol carries no @ session suffix. |
--interval | 1m | Bar interval (1s/5m/1h/1d style); time bars only. |
--bar-kind | time | One of the fourteen kinds (see Bars beyond time). |
--threshold | 0 | Activity-bar close threshold, in the kind’s unit. |
--reversal-mult | 0 (= 2.0) | Renko reversal as a multiple of the brick size. |
--threshold-mode | static | Imbalance/runs: static or expectation. |
--ewma-span-bars | 0 | Expectation mode: EWMA span for expected bar size. |
--ewma-span-signal | 0 | Expectation mode: EWMA span for the signed rate. |
--init-expected-size | 0 | Expectation mode: expected-bar-size seed. |
--init-signed-rate | 0.5 | Expectation mode: signed-rate seed, in [0,1]. |
--lead-in | 0 | Event bars: constructor warm-up. The adapter feeds trades from the start minus this and discards the bars that close before the start (see Constructor lead-in). Refused on time bars and with a negative value. |
--capital | 100000 | Simulator starting cash. |
--commission-per-order | 0 | Flat commission per fill. |
--commission-per-share | 0 | Commission per share/contract. |
--slippage-ticks | 0 | Adverse slippage in ticks (x each symbol’s tick size) on market-style fills. |
--bracket-ambiguity | conservative | Same-bar bracket convention: conservative, optimistic, path_direction. |
--limit-fill | conservative | Limit fill rule: conservative (trade-through at tick resolution, touch at bar/path), through (trade-through at every resolution; backtest only) or optimistic (touch; diagnostic). |
--simulation-resolution | auto | auto, tick, or bar. |
--gtc-expiry | never | Fill simulator: the venue GTC termination model. never rests a GTC order until it fills, is cancelled or the run ends (byte-identical to before the flag); ibkr-quarter cancels it, reason GTC_EXPIRED, before the first bar whose trade date falls after the end of the calendar quarter following its submission’s trade date. A live venue applies its own rule, and the flag then prints one note. No config key. See GTC quarter-end cancellation. |
--lifetime | v1 | Order lifetime profile. v1 is the legacy profile, byte-identical to before the flag. v2 offers lifetime-v2 in Init (the strategy must accept it), answers every submission with an OrderUpdate and every cancel request with a CancelResponse, and grants lifecycle turns per instant; backtest and emulated-live strategy runs on the pb wire or stdio-csv-v2 (not CSV v1), refused on a continuous run and under --schema TRADES. Config key data.lifetime. See Lifecycle turns. |
--lifetime-turns | 0 (= 3) | With --lifetime v2: lifecycle turns granted per instant; 0 selects the default, 3, and a negative value is refused. The outcomes of the last permitted turn’s commands are deferred to the next event on a backtest and delivered at once, without a turn, on a live run; either way 2 is the smallest budget under which a turn’s own outcome can grant another. Config key data.lifetime-turns. |
--lifetime-hold-timeout | 0 (= 5m) | With --lifetime v2: how long the admission race guard holds an order behind a pending cancellation before rejecting it with hold_timeout, on the run’s event clock (bar closes), a hold as old as the timeout included; 0 selects the default, five minutes, and a negative value is refused (engine: order lifetime v2 needs a hold timeout above zero (0 selects the default 5m0s), got -1s). Ignored on a v1 run. Config key data.lifetime-hold-timeout. See The engine race guard. |
--max-working-orders | 0 (no limit) | With --lifetime v2: the admission policy’s limit on the instance’s working orders, held, pending-cancel and unknown ones and labelled attached orders included (cap_working_orders). A negative value is refused, and so is any admission limit on a v1 run. Config key data.max-working-orders. See The admission policy. |
--max-symbol-working-orders | 0 (no limit) | With --lifetime v2: the same limit on the working orders on each symbol (cap_symbol_working_orders). Config key data.max-symbol-working-orders. |
--max-order-quantity | 0 (no limit) | With --lifetime v2: the limit on the quantity of one order and of each attached order (cap_quantity). Config key data.max-order-quantity. |
--max-position | 0 (no limit) | With --lifetime v2: the limit, either way, on the position each symbol could reach if every working and held order executed, checked only at the end an order extends (cap_exposure). Config key data.max-position. |
--max-submissions | 0 (no budget) | With --lifetime v2 and --submission-window: the budget of new orders the policy accepts per window of event time (rate_budget); the two are set together. Config key data.max-submissions. |
--submission-window | 0 (no budget) | With --lifetime v2 and --max-submissions: the window of event time (a Go duration) the budget covers. Config key data.submission-window. |
--transport-requests | 0 (= 5) | With --lifetime v2, live: the transport scheduler sends at most this many submissions and cancel requests to the venue within any --transport-window of the run’s operational clock (bar closes on today’s stepped loop, so per bar), queued cancel requests first; 0 selects the default, 5. A negative value is refused, and so is any transport limit on a v1 run; a v2 backtest has no venue transport and ignores the three. Config key data.transport-requests. See The transport scheduler. |
--transport-window | 0 (= 1s) | With --lifetime v2, live: the window (a Go duration) --transport-requests covers, and the pause after the venue refuses a request for pacing; 0 selects the default, one second. Config key data.transport-window. |
--transport-queue | 0 (= 100) | With --lifetime v2, live: the most submissions the transport scheduler queues; a submission that finds the queue full is refused (transport_overload), and cancel requests are not counted; 0 selects the default, 100. Config key data.transport-queue. |
--include-path | off | Request each coarsened bar’s intra-bar path (BARS_TIME; serves_path adapters only) and use it for bar-resolution fills. |
--path-interval | empty | Exact constituent interval, e.g. 1m; implies --include-path. Unavailable or structurally invalid paths are refused. |
--accept-degraded-seams | off | Continuous futures: trade across a served roll seam whose pair is a fallback (degraded) instead of refusing the run (SEAM_DEGRADED); recorded in degradation.json and on the manifest pin (GLE-323). Config key accept-degraded-seams. |
--continuous-clock | session | Continuous futures: session reads the feed’s trade-date session composite for a 1d/1w series (under --session, or eth when none is given) and UTC epoch buckets for an intraday interval; epoch reads epoch buckets at every interval and takes no session (the daily clock before GLE-324). A session together with the epoch clock, or any other value, is refused before any spawn. Config key continuous-clock. |
--exchange-calendar | off | Fetch the exchange calendar of every root the run reads (pb data wire; auto negotiation then prefers pb), push it to a strategy that asks for it and record it in the run’s provenance (result.json, --fills-json, --lifecycle-json), with no pin. A strategy that sets needs_calendar turns the fetch on by itself. Every bar of a root served a calendar is then checked against it, and a bar that disagrees refuses the run (calendar_data_disagree; see Conformance checks and admission). Refused under --schema TRADES, as is every calendar option. Config key data.exchange-calendar. See Engine side. |
--calendar-revisions root=rev[,root=rev...] | empty | Exchange-calendar pins: a served revision that differs, or no calendar served for a pinned root, refuses the run (calendar_pin_drift); a pin for a root the run does not read is ignored. Config key data.calendar-revisions, an object of root to revision. |
--strict-calendar | off | Require every symbol the run reads to have a calendar root with a pin and a served calendar that matches it (calendar_pin_drift). Config key data.strict-calendar. |
--calendar-accept-unverified root[,root...] | empty | The roots whose unrecorded session eras precise-time admission accepts (D-I11-4); it waives calendar_incomplete’s eras-unrecorded reason only, and nothing calls admission yet (see Conformance checks and admission). Config key data.calendar-accept-unverified, an array. |
--calendar-margin-quarters | 0 (= 2) | How many calendar quarters past the run’s last bar the exchange-calendar fetch reaches; 0 selects the default, 2, and at most 40. Config key data.calendar-margin-quarters. |
--path-heuristic | empty | Bar-resolution path assumption: legacy, midpoint, or empty for one ambiguous OHLC interval. |
--auto-lineage | off | Follow each equity series’ rename chain forward and run it as one instrument lineage; a discovered successor inherits the head’s adj= qualifier, interval and session. |
--mode | backtest | backtest uses the simulator; live selects the IBKR venue path. |
--venue-url URL | Required with live mode: IBKR gateway or emulator base URL. | |
--venue-account ID | venue-selected | Live IBKR account; empty asks the venue for its selected account. |
--venue-emulated | off | Drive the deterministic IBKR emulator clock. Currently required by live mode. |
--ledger PATH | Required with live mode: durable order identity and reconciliation ledger. | |
--on-orphan | exit | Live startup policy for an unexplained broker order. Only exit is supported. |
--deployment LABEL | algo | Live mode: the ledger’s deployment label, 1–40 characters from [A-Za-z0-9_]. The ledger pairs it with a nonce drawn once when it is created, and every order reference (the IBKR cOID) is <label>-<nonce>-<n>; a ledger created under another label refuses to open. Config key data.deployment. See The order ledger. |
--ledger-migration | empty | Live mode: exclusive-owner accepts a ledger written before deployment identity existed (every reference c-<n>) on the operator’s assertion that no other deployment on the account allocated references under that prefix, recording the prefix as owned; empty refuses such a ledger. Config key data.ledger-migration. |
--venue-reply-allow | empty (= o10151,o10152,o10153,o10331,p12) | Live mode, both lifetime profiles: the IBKR order reply message ids the venue confirms, comma-separated. A reply carrying any other id, or none, is declined, and its order denied with IBKR’s text (reply_declined). none confirms no reply; empty selects the default, IBKR’s five general risk disclosures, so every precaution is declined. Each id is 1 to 32 ASCII letters and digits, listed once and matched exactly; the list is checked before any spawn on every run, a backtest included, which ignores it. Config key data.venue-reply-allow, a list ([] confirms no reply). See Order reply messages. |
--start / --end | open range | RFC 3339 request window (end exclusive). |
--replicate | 1 | Total copies of the fetched bars (benchmarking; time bars only). |
--batch-size | 4096 | Records per data response envelope. |
--schema | BARS | BARS, or TRADES for a data-plane benchmark with no strategy. |
--run-id | derived | Run identifier (default run-<symbol>-<interval>, symbols joined by +, a continuous symbol slugified; mixed intervals give run-<label>+<label>, an event-bar run run-<symbol>-<kind>). |
--fills-json PATH | Backtest fill blotter and summary equity in JSON, used for reproducible comparisons. | |
--lifecycle-json PATH | Backtest strategy runs only: the order lifecycle trace, schema algolang.lifecycle/1 — every submission in the strategy’s and the venue’s frames, every cancel request, every venue fill and cancel, each continuous roll, the working set before the end-of-data cancellation, 25 summary counts and the fill blotter. Refused in live mode and under --schema TRADES; no config key. See The order lifecycle trace. | |
| `–report on | off` | on |
--risk-free-rate | 0 | Annual decimal risk-free rate for the performance report’s Sharpe ratio. |
| `–roll-trades stitch | split` | stitch |
--results-dir DIR | Per-run artefact root. Continuous runs may write manifest.yaml, audit.jsonl, and a conditional degradation.json; a run of several continuous series writes each series’ manifest and ledger under continuous/<series>/ (GLE-425). | |
--cache | on | Bar-series disk cache: off, on, or refresh (bypass reads, rewrite entries). Engages only for backtests with a fully historical --end; see “The series cache”. Env fallback ALGO_CACHE applies when the flag is not given. |
--cache-dir DIR | ~/algolang/cache | Cache directory. Env fallback ALGO_CACHE_DIR. |
--symbol-registry and --served-roll-schedules were removed by ER3 (GLE-325, owner Decision 4): algo run treats either as an unknown flag (flag provided but not defined), and the config keys symbol-registry and data.served-roll-schedules, refused for one release, are since ER5 (GLE-327) unknown fields ignored with a warning. A continuous run names the bare root fut:<VENUE>:<ROOT> or the composite fut:<VENUE>:<ROOT>:cont:adj=<panama|ratio|none>; see How continuous contracts are stitched. The config keys data.adjustment-mode and data.dividend-treatment are refused the same way for one release (GLE-328, GLE-228 Decision 5a): the equity price view is named on the symbol, eq:<VENUE>:<TICKER>:adj=split or adj=splitdiv, and there was no flag for it.
Config mode:
| Flag | Meaning |
|---|---|
--config FILE | Run-config JSON file (see Config files and run matrices). Excludes all single-run flags. |
--verify | Validate and print the expanded plan and run each run’s pre-flight checks against its adapter, as algo run does before its first fetch; execute nothing. Prints the error under any run that would fail, omits OK and exits non-zero. |
--date-from / --date-to | Override every run’s date range (YYYY-MM-DD, --date-to inclusive). |
--initial-capital | Override the capital pool (e.g. USD100000). |
--session | Override every run’s session: a trading-day container, or an intraday grid boundary. |
--bar-interval | Override every run’s bar interval. |
--results-dir | Override the global per-run artefacts directory (global-only setting). |
--cache / --cache-dir | Override the global cache / cache-dir settings (global-only). |
| `–report on | off` |
--risk-free-rate | Override the global report.risk-free-rate (annual decimal, Sharpe only). |
| `–roll-trades stitch | split` |
report.benchmark (config) | Benchmark comparison; default true. false restores the pre-benchmark artefacts byte-for-byte. |
report.benchmarks (config) | The benchmarks to compare against; a list of hold baskets and rate cash balances, exactly one primary. Defaults to Long ES, ES/NQ 50:50 and 3M-T-Bill cash. A sleeve the feed refuses is skipped with a warning and named as excluded on the page (GLE-324 W10); see Report benchmark findings. |
Also: algo version prints the build ID, algo cache [stats|list|flush] manages the series cache (see “The series cache”), and algo report <results-dir> [--runs id1,id2] [--partial] [--out DIR] [--format text|json] re-renders and recombines persisted run artefacts offline (see “The performance report”).
Strategy executable flags
Every SDK strategy answers --algolang-describe (JSON schema), --algolang-version (SDK version), and --algolang-selftest (200 synthetic bars; exits non-zero on any error). Any other --algolang-* flag is an error.
The algolang tag, condensed
algolang:"default=V,min=V,max=V,by=V,desc=TEXT,values=[a,b,c],required"
Comma-separated; values excludes min/max/by; single quotes protect commas in free text (desc='Max positions, long and short'); field types int, int64, float64, bool, string, time.Duration; tagged fields must be exported.
File formats
Bar CSV (file-csv adapter, csv2bars output): symbol,ts_open,ts_close,open,high,low,close,volume header, RFC 3339 timestamps, plain decimal floats, one bar per line, single interval per file.
Databento trades CSV (databento adapter, csv2dbn/csv2bars/ replicate input): the standard Databento trades export – header ts_recv,ts_event,rtype,publisher_id,instrument_id,action,side,depth,price,size,flags,ts_in_delta,sequence,symbol, epoch-nanosecond timestamps, fixed-point prices scaled by 1e-9.
DBN (databento adapter, csv2dbn output): Databento’s binary format, auto-detected by the adapter from the file content.
Fill blotter (--fills-json): one JSON object with capital, equity, realized and fills, the simulator’s fill reports, preceded by calendars, the run’s exchange-calendar provenance, when the run asked for exchange calendars (Engine side; absent otherwise). The lifecycle trace repeats the four as its last four keys; see the next section.