# 📈 Trading CLI

> Local, multi-account **paper-trading** engine for humans and AI agents.
> Live terminal dashboard, Alpaca-style orders, REST + MCP server. SQLite state,
> Yahoo Finance market data. Simulation only — **never places live brokerage orders**. 🚫💸

| 🧺 Assets | 🛠️ Engine |
|---|---|
| Stocks / ETFs / crypto (`BTC-USD`) / FX (`EURUSD=X`) / futures (`ES=F`) / equity options (OCC `AAPL260116C00250000`) | `market / limit / stop / stop_limit / trailing_stop` + `bracket / OCO / OTO / mleg` with `take_profit / stop_loss`, notional sizing, client order IDs, TIF (`gtc / day / ioc / fok / opg / cls`), extended-hours limit orders |

## ⚙️ Setup

Requires Python 3.10+ and Bun >=1.4.1 (the `tradingcli-tui` dashboard runs on Bun + OpenTUI).

```bash
# from source
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt          # or: pip install -e .
(cd tui && bun install)                  # TUI deps (Bun + OpenTUI)

# isolated tool install (uv)
uv tool install .
```

🗄️ Database defaults to `~/.papertrade.db`; override with `PAPERTRADE_DB=/tmp/test.db` or `PAPERTRADE_DB=:memory:` for isolated in-memory tests.

## 🚀 Run

```bash
# first-run wizard + live TUI dashboard 🖥️ (Bun + OpenTUI)
python3 papertrade.py            # or: tradingcli
# explicit dash
python3 papertrade.py dash       # or: tradingcli dash (or: tradingcli-tui)
# legacy Rich dashboard
python3 papertrade.py dash --rich
```

```bash
# headless snapshot for agents / scripting 🤖 (single JSON envelope, no TTY)
tradingcli-tui --headless --json snapshot
tradingcli-tui --headless --json snapshot -a mybook
tradingcli-tui --headless --json backtest -a mybook --lookback-days 1825
```

### 👛 Accounts

```bash
python3 papertrade.py new mybook --cash 50000
python3 papertrade.py accounts --json
python3 papertrade.py use mybook
```

### 💹 Trade → inspect

```bash
python3 papertrade.py buy AAPL 5 -a mybook
python3 papertrade.py positions -a mybook --json
python3 papertrade.py market --json
```

### 🔄 Alpaca-style order lifecycle

```bash
python3 papertrade.py order submit AAPL --side buy --qty 10 --type limit --limit-price 185 -a mybook
python3 papertrade.py order submit AAPL --side sell --qty 10 --type trailing-stop --trail-percent 3 -a mybook
python3 papertrade.py order get --order-id 2 --json   # pending limit from above
python3 papertrade.py order replace 2 --limit-price 184
python3 papertrade.py order cancel-all -a mybook
python3 papertrade.py order submit AAPL --side buy --qty 10 --type limit --limit-price 180 --dry-run --json
python3 papertrade.py position close AAPL --percent 50 -a mybook
python3 papertrade.py position close-all -a mybook
```

### 🧷 Brackets, options, watchlists, research

```bash
# bracket / OCO / OTO — use --take-profit / --stop-loss / --stop-loss-limit
# options / chain / watchlists / research
python3 papertrade.py option get AAPL270115C00100000 --json
python3 papertrade.py option exercise AAPL270115C00100000 -a mybook
python3 papertrade.py chain AAPL 2027-01-15
python3 papertrade.py watchlist create Tech --symbols AAPL,MSFT,NVDA -a mybook
python3 papertrade.py watchlist quotes Tech -a mybook --json
python3 papertrade.py data bars AAPL --timeframe 1Day --limit 30 --json
python3 papertrade.py data snapshot AAPL --json
python3 papertrade.py data movers --json
python3 papertrade.py calendar --start 2026-07-01 --end 2026-07-31 --json

# backtest current holdings as a retrospective (see notes below)
python3 papertrade.py backtest -a mybook --lookback-days 1825 --commission-bps 10 --json
```

🤖 Every command accepts one automation flag: `--json` / `--csv` / `--quiet`. `--schema` prints the command tree without touching market data; `doctor` checks DB integrity.

Press `g` in the TUI to open **📊 Backtesting & Graphs** — live equity curve beside a `backtesting.py` current-holdings backtest (return, CAGR, vol, Sharpe, Sortino, costs, maxDD). Universe is the selected account's open positions; `6m / 1y / 2y / 5y / 10y / max` presets or exact days. CAGR uses real calendar elapsed time; options appear as `skipped` (no point-in-time chain history); futures use continuous series without roll costs. Curves are time-weighted, so deposits/withdrawals don't masquerade as alpha. The result has intentional look-ahead/survivorship bias — it's a "what if we held today's book" retrospective, not an OOS strategy test. Yahoo adjusted closes are used; crypto top-of-book is indicative.

## 🕸️ Web UI (unsupported)

`static/` excluded from the wheel; `web_ui.py` retained but unsupported — use the TUI, CLI `--json`, or MCP server instead.

## 🔌 MCP server (for Claude Code / Cursor / Hermes)

Preferred surface for AI agents — typed, idempotent, single DB contract.

```bash
python3 mcp_server.py                              # core — 60 tools (default, safe)
PAPERTRADE_MCP_PROFILE=advanced python3 mcp_server.py  # 72 tools — adds destructive/specialist ops
PAPERTRADE_MCP_PROFILE=full python3 mcp_server.py      # 79 tools — adds legacy aliases (buy/sell/quote/…)
PAPERTRADE_MCP_RESPONSE_FORMAT=json python3 mcp_server.py  # force JSON contract
# or via entry point after pip install -e .
tradingcli-mcp
```

`core` responses use `{"ok": true, "data": …}` / `{"ok": false, "error": {"code": "…", "message": "…"}}`. `mcp_catalog` reports the active profile + tool list. Mutating tools take `idempotency_key` + `agent` for safe retries.

**Client config** 🔧 — copy `.mcp.json` to your client's MCP config and fix the path:

```json
{
  "mcpServers": {
    "papertrade": {
      "command": "python3",
      "args": ["/absolute/path/to/Trading-CLI/mcp_server.py"],
      "env": { "PAPERTRADE_MCP_PROFILE": "core" }
    }
  }
}
```

For agents importing as a library instead of MCP, see `docs/agent-guide.md`.

## ✅ Verify

Tests are standalone scripts (no `pytest` needed):

```bash
python3 test_papertrade.py
python3 test_backtesting.py
python3 test_performance.py
python3 test_concurrency.py
python3 test_mcp_server.py
python3 test_mcp_profiles.py
python3 test_dashboard.py
python3 test_alpaca_parity.py
python3 test_cli.py
python3 test_edge_cases.py
python3 test_market_data.py
python3 test_mcp_features.py
python3 test_invariants.py
python3 test_tui_parity.py
python3 test_quote_cache.py
```

```bash
bun test ./tui/tests/
```


```bash
tradingcli config list
tradingcli config set myapp.threshold 42
tradingcli events --since-id 0 --limit 20 --json
tradingcli export -a mybook --format parquet --output mybook.parquet
tradingcli perf -a mybook --benchmark SPY --json
```

Yahoo Finance supplies market data. Historical quote/trade series and crypto top-of-book are explicitly marked aggregated/indicative — not exchange tick tapes or full depth.