Skip to content
Holdout LabHoldout Lab

Command-line research

Everything in the gauntlet and the multi-instrument engines is available as a command, for scripting and unattended research. Run from backend/ with uv run python -m <module> …. The registry imports fresh each invocation, so a brand-new strategy file works without restarting the worker. CLI runs write the same BacktestRun rows the UI does, so results show up on the Backtests and Research tabs.

The full ladder, one command

Section titled “The full ladder, one command”
Terminal window
uv run python -m ats.research --strategy ibs_reversion --symbols SPY,TLT,GLD

Runs the whole evidence ladder for a strategy: rule test → split optimize (train window only) → WFO → a final run feeding the deflated Sharpe. For an intraday strategy, point it at the intraday catalog and charge the measured spread:

Terminal window
uv run python -m ats.research --strategy intraday_orb --symbols QQQ,SPY,DIA \
    --bar-spec 1-MINUTE-LAST --slippage-bps auto --start 2023-04-01 --end 2026-06-12

--slippage-bps auto resolves to each name’s measured half-spread (daily runs default to 0, byte-identical).

The unattended sweep

Section titled “The unattended sweep”
Terminal window
uv run python -m ats.sweep

Runs a cheap rule-test screen across the whole basket and both timeframes, then the deep gauntlet on the survivors, and prints a ready-first leaderboard. It publishes progress + ETA to Redis, which the UI shows as a sweep progress bar. This is the “test lots of strategies, walk away” command.

By default the cells are intraday_* strategies on the 1-minute ETFs and every other strategy on the daily basket. Use the key flags to shape and bound the run:

Flag Default What it does
--strategies all (with a search space) Comma-separated keys to test
--bar-specs (off) Comma-separated intraday bar specs — see below
--venue XNAS Instrument venue for every cell — CRYPTO to sweep crypto pairs
--params (off) JSON base params for every cell (e.g. sizing); the optimizer tunes on top
--time-budget-min 600 Hard wall-clock cap; checked between cells
--pass1-sims 40 Rule-test random twins in the screen
--pass2-trials 30 Optimize/WFO trials in the deep gauntlet
--screen-pctile 75 Min rule-test percentile to advance (marginal+)
--resume off Skip cells already deep-dived today (idempotent — safe to re-run)

Multiple intraday timeframes (--bar-specs)

Section titled “Multiple intraday timeframes (--bar-specs)”

By default a bar-agnostic strategy like ibs_reversion only runs daily. Pass --bar-specs to instead test those strategies on the intraday ETFs at each listed timeframe — the engine resamples the 1-minute source on the fly, so no extra data is pulled. The session-aware intraday_* strategies stay pinned to 1-minute (their VWAP / opening-range needs it).

Terminal window
# the most promising reversion/momentum strategies across 4 intraday resolutions, 7.5h cap
uv run python -m ats.sweep \
  --strategies ibs_reversion,down_streak,tsmom,atr_trailing_stop \
  --bar-specs 1-HOUR-LAST,30-MINUTE-LAST,15-MINUTE-LAST,5-MINUTE-LAST \
  --time-budget-min 450 --resume

Cells = strategies × intraday symbols × timeframes, ordered strategy-major then coarse-to-fine, so under a tight budget the highest-value (cheapest, lowest-cost-drag) cells are gauntleted first; whatever the cap cuts off, --resume finishes on the next run. Coarser bars trade less, so the measured spread (the cost that sinks 1-minute strategies) bites least. Use Nautilus bar tokens — 5-MINUTE-LAST, 15-MINUTE-LAST, 30-MINUTE-LAST, 1-HOUR-LAST (note: 60-MINUTE is not a valid token, use 1-HOUR).

Sweeping crypto (--venue CRYPTO)

Section titled “Sweeping crypto (--venue CRYPTO)”

Crypto pairs need three differences from the equity default — pass them explicitly since the equity intraday_aux auto-discovery doesn’t apply:

Terminal window
uv run python -m ats.sweep \
  --strategies ibs_reversion,down_streak,tsmom,atr_trailing_stop \
  --venue CRYPTO --intraday-symbols BTCUSD,ETHUSD,SOLUSD,XRPUSD,DOGEUSD,ADAUSD \
  --bar-specs 1-HOUR-LAST,30-MINUTE-LAST,15-MINUTE-LAST \
  --params '{"sizing_mode":"vol_target","risk_pct":1.0,"max_gross_notional":95000}' \
  --start 2024-06-20 --end 2026-06-20 --time-budget-min 450
  • --venue CRYPTO resolves each symbol to <SYM>.CRYPTO, which triggers 365-day annualization and the taker-fee model (so cost is charged even though crypto has no measured-spread sidecar).
  • --params sizing is required. A fixed share count mis-sizes wildly across coin prices (100 units is $6M of BTC but $10 of DOGE); capping max_gross_notional to ~equity and letting vol-target fill it gives every coin a comparable, re-entrant position.
  • Pass explicit --start/--end (the intraday window-from-data discovery is equity-only) and don’t use --resume for crypto (its done-check keys on the equity venue).
  • Crypto bars come from Binance public klines (free, no key, no rate limit) — ingest 1-min once (ingest-crypto or the one-click crypto basket) and the resampler derives 5/15/30-min for the sweep.

The engines

Section titled “The engines”
Command What it does Doc
python -m ats.research The full single-instrument ladder the gauntlet
python -m ats.sweep Adaptive, unattended screen + gauntlet across the basket above
python -m ats.cross_sectional Cross-sectional rank/hold over a universe multi-instrument
python -m ats.intraday_relval Session-aware intraday relative value multi-instrument
python -m ats.pairs A cointegrated pair (with hedge β options) multi-instrument
python -m ats.pair_screen Discover cointegrated pair candidates multi-instrument
python -m ats.portfolio Blend validated sleeves multi-instrument
python -m ats.portfolio_search Search subsets × allocators for held-out Sharpe multi-instrument
python -m ats.book Faithful shared-account book backtest multi-instrument
python -m ats.overnight Overnight-effect study —
python -m ats.paper / ats.live The paper / live trading runners paper, live
python -m ats.crypto_paper The local crypto paper simulator paper

Admin & account CLI (ats.cli)

Section titled “Admin & account CLI (ats.cli)”

python -m ats.cli <command> handles account and operational tasks (run from backend/):

Command What it does
create-user --username <you> Create the single dashboard account (prompts for a password).
reset-password --username <you> Set a new password (the login screen’s “Forgot password?” points here).
alert-test Send a test Telegram alert using the .env credentials.
approve-live --strategy <key> --instrument <id> --note "…" Record the audited go-live sign-off (the live runner refuses to start without it). See live trading.
revoke-live --strategy <key> --instrument <id> Remove a go-live approval.
ingest --symbol <sym> … Pull daily bars from Tiingo into the catalog (CLI ingest).
Section titled “Related”