speculo 0.1.0

Speculo Studio CLI — backtest your trading strategies locally and sync results.

Speculo CLI

Run Speculo Studio backtests on your own machine — your hardware, your data, results synced to your Studio history.

Install

pip install speculo

Authenticate

Create a CLI token in Studio → Settings → CLI tokens, then:

speculo login --token spk_xxxxxxxxxxxx
# self-hosted / staging:
speculo login --token spk_xxx --api https://api.staging.speculotrading.com

Credentials are stored in ~/.speculo/config.json (mode 600). You can also set SPECULO_TOKEN / SPECULO_API in the environment.

Backtest

# real historical data (fetched via the platform's cached proxy)
speculo backtest strategy.py --symbol AAPL --timeframe 1d --capital 100000

# your own OHLCV CSV
speculo backtest strategy.py --csv mydata.csv

# synthetic demo series
speculo backtest strategy.py --bars 500

Add --no-sync to keep a run private (compute locally, don't upload).

Strategy contract

A strategy defines on_bar(ctx) and optionally initialize(ctx) — identical to the web editor:

def initialize(ctx):
    ctx.state["fast"], ctx.state["slow"] = 5, 20

def on_bar(ctx):
    c = ctx.closes()
    if len(c) < ctx.state["slow"]:
        return
    fast = sum(c[-ctx.state["fast"]:]) / ctx.state["fast"]
    slow = sum(c[-ctx.state["slow"]:]) / ctx.state["slow"]
    if fast > slow and ctx.position == 0:
        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="BUY", order_type="MARKET")
    elif fast < slow and ctx.position > 0:
        ctx.broker.place_order(symbol=ctx.symbol, quantity=10, side="SELL", order_type="MARKET")

The backtest engine itself is fetched from the platform at runtime, so the CLI always runs the exact same engine as the web app.