@backtest-kit/cli 8.3.1 → 8.4.1

package/README.md

@@ -1371,7 +1371,7 @@ npm run sync:lib
 
 ## 🐳 Running in Docker (`--docker`)
 
-CLI can scaffold a ready-to-use Docker workspace: self-contained directory with `docker-compose.yaml` and a strategy entry point. 
+CLI can create a ready-to-use Docker workspace: self-contained directory with `docker-compose.yaml` and a strategy entry point. 
 
 ### CLI Flags
 
@@ -1396,20 +1396,48 @@ npx @backtest-kit/cli --docker --output my-docker-workspace
 
 The target directory must not exist or must be empty — the command aborts if it contains any files.
 
-### Generated Workspace Structure
+### Two Launch Modes
 
+The Docker image entrypoint supports two ways to run a strategy:
+
+#### 1. `command:` in `docker-compose.yaml`
+
+Pin mode and flags directly in the compose file. The entrypoint forwards all arguments to the CLI unchanged:
+
+```yaml
+command:
+  - --live
+  - --symbol
+  - TRXUSDT
+  - --strategy
+  - feb_2026_strategy
+  - --exchange
+  - ccxt-exchange
+  - ./content/feb_2026/feb_2026.strategy.ts
+  - --ui
 ```
-backtest-kit-docker/
-├── docker-compose.yaml           # ready-to-run service definition
-├── .env.example                  # environment variable reference
-├── package.json                  # dependencies for editing strategies locally
-├── tsconfig.json                 # TypeScript config for content/
-└── content/
-    └── feb_2026/
-        ├── feb_2026.strategy.ts  # example strategy entry point
-        └── modules/
-            └── backtest.module.ts  # CCXT Binance exchange + frame schema
-```
+
+#### 2. Inline environment variables
+
+Pass `MODE` and `STRATEGY_FILE` on the command line — no file edits needed:
+
+```bash
+MODE=live SYMBOL=TRXUSDT UI=1 docker-compose up -d
+```
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MODE` | yes | — | `backtest` \| `live` \| `paper` \| `walker` |
+| `STRATEGY_FILE` | yes | — | Path to strategy entry point (relative to `working_dir`) |
+| `SYMBOL` | no | `BTCUSDT` | Trading pair |
+| `STRATEGY` | no | first registered | Strategy name |
+| `EXCHANGE` | no | first registered | Exchange name |
+| `FRAME` | no | first registered | Frame name (backtest only) |
+| `UI` | no | — | Any non-empty value enables `--ui` |
+| `TELEGRAM` | no | — | Any non-empty value enables `--telegram` |
+| `VERBOSE` | no | — | Any non-empty value enables `--verbose` |
+| `NO_CACHE` | no | — | Any non-empty value enables `--noCache` |
+| `NO_FLUSH` | no | — | Any non-empty value enables `--noFlush` |
 
 ## 🌍 Environment Variables
 

package/build/index.cjs

@@ -3026,7 +3026,7 @@ const main$f = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.3.1"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.4.1"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
@@ -3706,6 +3706,9 @@ const main$2 = async () => {
     }
     console.log(`Creating Docker workspace in ${projectPath}`);
     await copyDir(templatePath, projectPath);
+    console.log(`Installing env...`);
+    await fs$1.copyFile(path.join(projectPath, ".env.example"), path.join(projectPath, ".env"));
+    console.log(`  -> ${path.join(projectPath, ".env")}`);
     console.log(`Installing dependencies...`);
     await runNpmInstall(projectPath);
     console.log(`Done! Docker workspace created at ${projectPath}`);
@@ -3904,7 +3907,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.3.1"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.4.1"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -3918,7 +3921,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.3.1"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.4.1"}\n`);
     process.exit(0);
 };
 main();

package/build/index.mjs

@@ -2997,7 +2997,7 @@ const main$f = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.3.1"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.4.1"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
@@ -3677,6 +3677,9 @@ const main$2 = async () => {
     }
     console.log(`Creating Docker workspace in ${projectPath}`);
     await copyDir(templatePath, projectPath);
+    console.log(`Installing env...`);
+    await copyFile(join(projectPath, ".env.example"), join(projectPath, ".env"));
+    console.log(`  -> ${join(projectPath, ".env")}`);
     console.log(`Installing dependencies...`);
     await runNpmInstall(projectPath);
     console.log(`Done! Docker workspace created at ${projectPath}`);
@@ -3875,7 +3878,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.3.1"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.4.1"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -3889,7 +3892,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.3.1"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.4.1"}\n`);
     process.exit(0);
 };
 main();

package/docker/README.md

@@ -0,0 +1,122 @@
+<img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/square_compasses.svg" height="45px" align="right">
+
+# 🧿 Backtest Kit Docker
+
+> A TypeScript framework for backtesting and live trading strategies on multi-asset, crypto, forex or [DEX (peer-to-peer marketplace)](https://en.wikipedia.org/wiki/Decentralized_finance#Decentralized_exchanges), spot, futures with crash-safe persistence, signal validation, and AI optimization.
+
+![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot16.png)
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
+[![npm](https://img.shields.io/npm/v/backtest-kit.svg?style=flat-square)](https://npmjs.org/package/backtest-kit)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
+
+A self-contained Docker workspace for running [backtest-kit](https://github.com/tripolskypetr/backtest-kit) strategies with automatic restarts and zero-downtime trading.
+
+---
+
+## 📂 Strategy Index
+
+| Strategy | Ticker | Period | Signal source | Net PNL | Sharpe |
+|---|---|---|---|---|---|
+| [DOTUSDT Feb 2021 — Python EMA Crossover](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/feb_2021.strategy) | DOTUSDT | Feb 2021 | Python EMA(9)/EMA(21) crossover via WebAssembly | **+5.52%** | **0.09** |
+| [BTCUSDT Oct 2021 — TensorFlow Neural Network](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/oct_2021.strategy) | BTCUSDT | Oct 2021 | TensorFlow NN predicting next candle close | **+18.26%** | **0.31** |
+| [BTCUSDT Dec 2025 — Pine Script Range Breakout](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/dec_2025.strategy) | BTCUSDT | Dec 2025 | Pine Script BB + range detector + volume spike | **+2.40%** | **0.06** |
+| [TRXUSDT Jan 2026 — Liquidity Harvesting](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content//jan_2026.strategy) | TRXUSDT | Jan 2026 | Telegram channel signals (inverted) | **+8.58%** | **1.14** |
+| [BTCUSDT Feb 2026 — AI News Sentiment](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/feb_2026.strategy) | BTCUSDT | Feb 2026 | LLM forecast on live news (Tavily + Ollama) | **+16.99%** | **0.25** |
+| [BTCUSDT Mar 2026 — SHORT DCA Ladder](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/mar_2026.strategy) | BTCUSDT | Mar 2026 | Fixed SHORT gravebag signal + DCA ladder up (up to 10 rungs) | **+37.83%** | **0.35** |
+| [BTCUSDT Apr 2026 — DCA Ladder](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/apr_2026.strategy) | BTCUSDT | Apr 2026 | Fixed LONG moonbag signal + DCA ladder down (up to 10 rungs) | **+67.85%** | **0.12** |
+
+---
+
+## 🚀 Quick Start
+
+```bash
+MODE=backtest STRATEGY_FILE=./content/feb_2026/feb_2026.strategy.ts docker-compose up -d
+docker-compose logs -f
+```
+
+---
+
+## 🏃 Running Modes
+
+The container entrypoint reads `MODE` and `STRATEGY_FILE` from environment variables. Pass them inline — no file edits needed.
+
+### 🧪 Backtest
+
+```bash
+MODE=backtest \
+STRATEGY_FILE=./content/feb_2026/feb_2026.strategy.ts \
+SYMBOL=BTCUSDT \
+STRATEGY=feb_2026_strategy \
+EXCHANGE=ccxt-exchange \
+UI=1 \
+docker-compose up -d
+```
+
+### 📄 Paper Trading
+
+```bash
+MODE=paper \
+STRATEGY_FILE=./content/feb_2026/feb_2026.strategy.ts \
+SYMBOL=BTCUSDT \
+docker-compose up -d
+```
+
+### 📈 Live Trading
+
+```bash
+MODE=live \
+STRATEGY_FILE=./content/feb_2026/feb_2026.strategy.ts \
+SYMBOL=BTCUSDT \
+UI=1 \
+docker-compose up -d
+```
+
+### ⚖️ Walker — A/B Comparison
+
+```yaml
+command:
+  - --walker
+  - --symbol
+  - BTCUSDT
+  - --noCache
+  - ./content/feb_2026_v1.strategy.ts
+  - ./content/feb_2026_v2.strategy.ts
+```
+
+---
+
+## 🌍 Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MODE` | yes | — | `backtest` \| `live` \| `paper` \| `walker` |
+| `STRATEGY_FILE` | yes | — | Path to strategy entry point (relative to `working_dir`) |
+| `SYMBOL` | no | `BTCUSDT` | Trading pair |
+| `STRATEGY` | no | first registered | Strategy name from `addStrategySchema` |
+| `EXCHANGE` | no | first registered | Exchange name from `addExchangeSchema` |
+| `FRAME` | no | first registered | Frame name from `addFrameSchema` (backtest only) |
+| `UI` | no | — | Any non-empty value enables `--ui` dashboard at `http://localhost:60050` |
+| `TELEGRAM` | no | — | Any non-empty value enables `--telegram` notifications |
+| `VERBOSE` | no | — | Any non-empty value enables `--verbose` candle logging |
+| `NO_CACHE` | no | — | Any non-empty value enables `--noCache` (skip cache warming) |
+| `NO_FLUSH` | no | — | Any non-empty value enables `--noFlush` (keep report folders) |
+
+Connection strings, API keys, and other secrets go in `.env` — it is loaded automatically by `docker-compose.yaml`.
+
+---
+
+## 🗂️ Project Structure
+
+```
+├── docker-compose.yaml               # service definition — edit to pin command: or add resources
+├── .env                              # secrets: DB connection strings, API keys, Telegram token
+├── .env.example                      # reference copy of .env
+├── package.json                      # dependencies for editing strategies locally
+├── tsconfig.json                     # TypeScript config for content/
+└── content/
+    └── feb_2026/
+        ├── feb_2026.strategy.ts      # strategy entry point
+        └── modules/
+            └── backtest.module.ts    # CCXT Binance exchange + frame schema
+```

package/docker/docker-compose.yaml

@@ -13,12 +13,20 @@ services:
     volumes:
       - ./:/workspace
     working_dir: /workspace
-    command:
-      - --backtest
-      - --symbol
-      - BTCUSDT
-      - --strategy
-      - feb_2026_strategy
-      - --exchange
-      - ccxt-exchange
-      - ./content/feb_2026/feb_2026.strategy.ts
+    env_file:
+      - .env
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:60050/api/v1/health/health_check"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    # command:
+    #   - --backtest
+    #   - --symbol
+    #   - BTCUSDT
+    #   - --strategy
+    #   - feb_2026_strategy
+    #   - --exchange
+    #   - ccxt-exchange
+    #   - ./content/feb_2026/feb_2026.strategy.ts
+    #   - --ui

package/docker/package.json

@@ -15,17 +15,17 @@
     "@types/node": "25.6.0"
   },
   "dependencies": {
-    "@backtest-kit/cli": "8.3.0",
-    "@backtest-kit/graph": "8.3.0",
-    "@backtest-kit/pinets": "8.3.0",
-    "@backtest-kit/signals": "8.3.0",
-    "@backtest-kit/ui": "8.3.0",
+    "@backtest-kit/cli": "8.4.1",
+    "@backtest-kit/graph": "8.4.0",
+    "@backtest-kit/pinets": "8.4.0",
+    "@backtest-kit/signals": "8.4.0",
+    "@backtest-kit/ui": "8.4.0",
     "@tavily/core": "0.7.2",
     "@tensorflow/tfjs": "4.22.0",
     "@tensorflow/tfjs-backend-wasm": "4.22.0",
     "@tensorflow/tfjs-core": "4.22.0",
     "agent-swarm-kit": "2.6.0",
-    "backtest-kit": "8.3.0",
+    "backtest-kit": "8.4.0",
     "dayjs": "1.11.20",
     "functools-kit": "2.3.0",
     "garch": "1.2.3",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtest-kit/cli",
-  "version": "8.3.1",
+  "version": "8.4.1",
   "description": "Zero-boilerplate CLI runner for backtest-kit strategies. Run backtests, paper trading, and live bots with candle cache warming, web dashboard, and Telegram notifications — no setup code required.",
   "author": {
     "name": "Petr Tripolsky",
@@ -63,11 +63,11 @@
   "devDependencies": {
     "@babel/plugin-transform-modules-umd": "7.27.1",
     "@babel/standalone": "7.29.1",
-    "@backtest-kit/graph": "8.3.0",
-    "@backtest-kit/ollama": "8.3.0",
-    "@backtest-kit/pinets": "8.3.0",
-    "@backtest-kit/signals": "8.3.0",
-    "@backtest-kit/ui": "8.3.0",
+    "@backtest-kit/graph": "8.4.0",
+    "@backtest-kit/ollama": "8.4.0",
+    "@backtest-kit/pinets": "8.4.0",
+    "@backtest-kit/signals": "8.4.0",
+    "@backtest-kit/ui": "8.4.0",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-typescript": "11.1.6",
     "@types/image-size": "0.7.0",
@@ -75,7 +75,7 @@
     "@types/mustache": "4.2.6",
     "@types/node": "22.9.0",
     "@types/stack-trace": "0.0.33",
-    "backtest-kit": "8.3.0",
+    "backtest-kit": "8.4.0",
     "glob": "11.0.1",
     "markdown-it": "14.1.1",
     "rimraf": "6.0.1",
@@ -90,12 +90,12 @@
   "peerDependencies": {
     "@babel/plugin-transform-modules-umd": "^7.27.1",
     "@babel/standalone": "^7.29.1",
-    "@backtest-kit/graph": "^8.3.0",
-    "@backtest-kit/ollama": "^8.3.0",
-    "@backtest-kit/pinets": "^8.3.0",
-    "@backtest-kit/signals": "^8.3.0",
-    "@backtest-kit/ui": "^8.3.0",
-    "backtest-kit": "^8.3.0",
+    "@backtest-kit/graph": "^8.4.0",
+    "@backtest-kit/ollama": "^8.4.0",
+    "@backtest-kit/pinets": "^8.4.0",
+    "@backtest-kit/signals": "^8.4.0",
+    "@backtest-kit/ui": "^8.4.0",
+    "backtest-kit": "^8.4.0",
     "markdown-it": "^14.1.1",
     "typescript": "^5.0.0"
   },

package/template/project/README.md

@@ -11,6 +11,20 @@
 
 A minimal project scaffold for [backtest-kit](https://github.com/tripolskypetr/backtest-kit). All infrastructure (exchange registration, candle caching, runner, UI, Telegram) is handled by `@backtest-kit/cli` — this project contains only your strategy files.
 
+
+## 📂 Strategy Index
+
+| Strategy | Ticker | Period | Signal source | Net PNL | Sharpe |
+|---|---|---|---|---|---|
+| [DOTUSDT Feb 2021 — Python EMA Crossover](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/feb_2021.strategy) | DOTUSDT | Feb 2021 | Python EMA(9)/EMA(21) crossover via WebAssembly | **+5.52%** | **0.09** |
+| [BTCUSDT Oct 2021 — TensorFlow Neural Network](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/oct_2021.strategy) | BTCUSDT | Oct 2021 | TensorFlow NN predicting next candle close | **+18.26%** | **0.31** |
+| [BTCUSDT Dec 2025 — Pine Script Range Breakout](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/dec_2025.strategy) | BTCUSDT | Dec 2025 | Pine Script BB + range detector + volume spike | **+2.40%** | **0.06** |
+| [TRXUSDT Jan 2026 — Liquidity Harvesting](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content//jan_2026.strategy) | TRXUSDT | Jan 2026 | Telegram channel signals (inverted) | **+8.58%** | **1.14** |
+| [BTCUSDT Feb 2026 — AI News Sentiment](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/feb_2026.strategy) | BTCUSDT | Feb 2026 | LLM forecast on live news (Tavily + Ollama) | **+16.99%** | **0.25** |
+| [BTCUSDT Mar 2026 — SHORT DCA Ladder](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/mar_2026.strategy) | BTCUSDT | Mar 2026 | Fixed SHORT gravebag signal + DCA ladder up (up to 10 rungs) | **+37.83%** | **0.35** |
+| [BTCUSDT Apr 2026 — DCA Ladder](https://github.com/tripolskypetr/backtest-kit/tree/master/example/content/apr_2026.strategy) | BTCUSDT | Apr 2026 | Fixed LONG moonbag signal + DCA ladder down (up to 10 rungs) | **+67.85%** | **0.12** |
+
+
 ## 📋 Quick Start
 
 ```bash
@@ -87,7 +101,7 @@ npm start -- --live --symbol BTCUSDT --ui --telegram ./content/feb_2026.strategy
 
 Module file `./modules/live.module.ts` is loaded automatically if it exists. Use it to register a `Broker` adapter that intercepts every trade mutation before internal state changes — exchange rejection rolls back the operation atomically.
 
-## ⚖️ Walker — A/B Strategy Comparison (`--walker`)
+## ⚖️ Walker — A/B Comparison
 
 Runs the same historical period across multiple strategy files and prints a ranked comparison report. Use it to pick the best variant before committing to a single strategy.
 

package/template/project/package.mustache

@@ -13,12 +13,12 @@
   "license": "ISC",
   "type": "commonjs",
   "dependencies": {
-    "@backtest-kit/cli": "^8.3.0",
-    "@backtest-kit/graph": "^8.3.0",
-    "@backtest-kit/pinets": "^8.3.0",
-    "@backtest-kit/ui": "^8.3.0",
+    "@backtest-kit/cli": "^8.4.1",
+    "@backtest-kit/graph": "^8.4.0",
+    "@backtest-kit/pinets": "^8.4.0",
+    "@backtest-kit/ui": "^8.4.0",
     "agent-swarm-kit": "^2.6.0",
-    "backtest-kit": "^8.3.0",
+    "backtest-kit": "^8.4.0",
     "functools-kit": "^2.3.0",
     "garch": "^1.2.3",
     "get-moment-stamp": "^1.1.2",