Metadata-Version: 2.4
Name: speculo
Version: 0.1.0
Summary: Speculo Studio CLI — backtest your trading strategies locally and sync results.
Author: Speculo
License: Proprietary
Project-URL: Homepage, https://speculotrading.com
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Speculo CLI

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

## Install

```bash
pip install speculo
```

## Authenticate

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

```bash
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

```bash
# 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:

```python
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.
