@backtest-kit/cli 0.0.2 → 0.0.4

package/README.md

@@ -30,13 +30,13 @@ Point the CLI at your strategy file, choose a mode, and it handles exchange conn
 
 `@backtest-kit/cli` wraps the `backtest-kit` engine and resolves all scaffolding automatically:
 
-| Mode             | Flag          | Description                                  |
-|------------------|---------------|----------------------------------------------|
-| **Backtest**     | `--backtest`  | Run strategy on historical candle data       |
-| **Paper**        | `--paper`     | Live prices, no real orders                  |
-| **Live**         | `--live`      | Real trades via exchange API                 |
-| **UI Dashboard** | `--ui`        | Web dashboard at `http://localhost:60050`    |
-| **Telegram**     | `--telegram`  | Trade notifications with price charts        |
+| Mode             | Command Line Args          | Description                                  |
+|------------------|----------------------------|----------------------------------------------|
+| **Backtest**     | `--backtest`               | Run strategy on historical candle data       |
+| **Paper**        | `--paper`                  | Live prices, no real orders                  |
+| **Live**         | `--live`                   | Real trades via exchange API                 |
+| **UI Dashboard** | `--ui`                     | Web dashboard at `http://localhost:60050`    |
+| **Telegram**     | `--telegram`               | Trade notifications with price charts        |
 
 ## 🚀 Installation
 
@@ -129,19 +129,19 @@ npm start -- --symbol BTCUSDT --ui
 
 ## 🎛️ CLI Flags
 
-| Flag          | Type    | Default              | Description                               |
-|---------------|---------|----------------------|-------------------------------------------|
-| `--backtest`  | boolean | `false`              | Run historical backtest                   |
-| `--paper`     | boolean | `false`              | Paper trading (live prices, no orders)    |
-| `--live`      | boolean | `false`              | Run live trading                          |
-| `--ui`        | boolean | `false`              | Start web UI dashboard                    |
-| `--telegram`  | boolean | `false`              | Enable Telegram notifications             |
-| `--verbose`   | boolean | `false`              | Log each candle fetch                     |
-| `--symbol`    | string  | `"BTCUSDT"`          | Trading pair                              |
-| `--strategy`  | string  | first registered     | Strategy name                             |
-| `--exchange`  | string  | first registered     | Exchange name                             |
-| `--frame`     | string  | first registered     | Backtest frame name                       |
-| `--cache`     | string  | `"1m, 15m, 30m, 4h"` | Intervals to pre-cache before backtest   |
+|     Command Line Args     | Type    | Description                                                        |
+|---------------------------|---------|--------------------------------------------------------------------|
+| `--backtest`              | boolean | Run historical backtest (default: `false`)                         |
+| `--paper`                 | boolean | Paper trading (live prices, no orders) (default: `false`)          |
+| `--live`                  | boolean | Run live trading (default: `false`)                                |
+| `--ui`                    | boolean | Start web UI dashboard (default: `false`)                          |
+| `--telegram`              | boolean | Enable Telegram notifications (default: `false`)                   |
+| `--verbose`               | boolean | Log each candle fetch (default: `false`)                           |
+| `--symbol`                | string  | Trading pair (default: `"BTCUSDT"`)                                |
+| `--strategy`              | string  | Strategy name (default: first registered)                          |
+| `--exchange`              | string  | Exchange name (default: first registered)                          |
+| `--frame`                 | string  | Backtest frame name (default: first registered)                    |
+| `--cache`                 | string  | Intervals to pre-cache before backtest (default: `"1m, 15m, 30m, 4h"`) |
 
 **Positional argument (required):** path to your strategy entry point file (set once in `package.json` scripts).
 
@@ -393,6 +393,89 @@ When your strategy module does not register an exchange, frame, or strategy name
 
 > **Note:** The default exchange schema **does not support order book fetching in backtest mode**. If your strategy calls `getOrderBook()` during backtest, you must register a custom exchange schema with your own snapshot storage.
 
+
+## 🔧 Programmatic API
+
+In addition to the CLI, `@backtest-kit/cli` can be used as a library — call `run()` directly from your own script without spawning a child process or parsing CLI flags.
+
+### `run(mode, args)`
+
+```typescript
+import { run } from '@backtest-kit/cli';
+
+await run(mode, args);
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `mode` | `"backtest" \| "paper" \| "live"` — Execution mode |
+| `args` | Mode-specific options (all optional — same defaults as CLI) |
+
+`run()` can be called **only once per process**. A second call throws `"Should be called only once"`.
+
+### Payload fields
+
+**Backtest** (`mode: "backtest"`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entryPoint` | `string` | Path to strategy entry point file |
+| `symbol` | `string` | Trading pair (default: `"BTCUSDT"`) |
+| `strategy` | `string` | Strategy name (default: first registered) |
+| `exchange` | `string` | Exchange name (default: first registered) |
+| `frame` | `string` | Frame name (default: first registered) |
+| `cacheList` | `CandleInterval[]` | Intervals to pre-cache (default: `["1m","15m","30m","1h","4h"]`) |
+| `verbose` | `boolean` | Log each candle fetch (default: `false`) |
+
+**Paper** and **Live** (`mode: "paper"` / `mode: "live"`):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `entryPoint` | `string` | Path to strategy entry point file |
+| `symbol` | `string` | Trading pair (default: `"BTCUSDT"`) |
+| `strategy` | `string` | Strategy name (default: first registered) |
+| `exchange` | `string` | Exchange name (default: first registered) |
+| `verbose` | `boolean` | Log each candle fetch (default: `false`) |
+
+### Examples
+
+**Backtest:**
+
+```typescript
+import { run } from '@backtest-kit/cli';
+
+await run('backtest', {
+  entryPoint: './src/index.mjs',
+  symbol: 'ETHUSDT',
+  frame: 'feb-2024',
+  cacheList: ['1m', '15m', '1h'],
+  verbose: true,
+});
+```
+
+**Paper trading:**
+
+```typescript
+import { run } from '@backtest-kit/cli';
+
+await run('paper', {
+  entryPoint: './src/index.mjs',
+  symbol: 'BTCUSDT',
+});
+```
+
+**Live trading:**
+
+```typescript
+import { run } from '@backtest-kit/cli';
+
+await run('live', {
+  entryPoint: './src/index.mjs',
+  symbol: 'BTCUSDT',
+  verbose: true,
+});
+```
+
 ## 💡 Why Use @backtest-kit/cli?
 
 Instead of writing infrastructure code for every project:

package/build/index.cjs

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 'use strict';
 
 var backtestKit = require('backtest-kit');
@@ -536,8 +537,8 @@ class BacktestMainService {
             });
             notifyFinish();
         });
-        this.init = functoolsKit.singleshot(async () => {
-            this.loggerService.log("backtestMainService init");
+        this.connect = functoolsKit.singleshot(async () => {
+            this.loggerService.log("backtestMainService connect");
             if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
                 return;
             }
@@ -613,8 +614,8 @@ class LiveMainService {
             });
             notifyFinish();
         });
-        this.init = functoolsKit.singleshot(async () => {
-            this.loggerService.log("liveMainService init");
+        this.connect = functoolsKit.singleshot(async () => {
+            this.loggerService.log("liveMainService connect");
             if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
                 return;
             }
@@ -683,8 +684,8 @@ class PaperMainService {
             });
             notifyFinish();
         });
-        this.init = functoolsKit.singleshot(async () => {
-            this.loggerService.log("paperMainService init");
+        this.connect = functoolsKit.singleshot(async () => {
+            this.loggerService.log("paperMainService connect");
             if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
                 return;
             }
@@ -1845,6 +1846,9 @@ const BEFORE_EXIT_FN$4 = functoolsKit.singleshot(async () => {
         frameName,
     });
 });
+const listenGracefulShutdown$4 = functoolsKit.singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$4);
+});
 const main$4 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
@@ -1853,7 +1857,8 @@ const main$4 = async () => {
     if (!values.backtest) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$4);
+    await cli.backtestMainService.connect();
+    listenGracefulShutdown$4();
 };
 main$4();
 
@@ -1873,6 +1878,9 @@ const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
         strategyName,
     });
 });
+const listenGracefulShutdown$3 = functoolsKit.singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$3);
+});
 const main$3 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
@@ -1881,7 +1889,8 @@ const main$3 = async () => {
     if (!values.paper) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$3);
+    cli.paperMainService.connect();
+    listenGracefulShutdown$3();
 };
 main$3();
 
@@ -1902,6 +1911,9 @@ const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
     });
     backtestKit.listenDoneLive(cli.liveProviderService.disable);
 });
+const listenGracefulShutdown$2 = functoolsKit.singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$2);
+});
 const main$2 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
@@ -1910,7 +1922,8 @@ const main$2 = async () => {
     if (!values.live) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$2);
+    await cli.liveMainService.connect();
+    listenGracefulShutdown$2();
 };
 main$2();
 
@@ -1919,6 +1932,9 @@ const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
     notifyShutdown();
     cli.frontendProviderService.disable();
 });
+const listenGracefulShutdown$1 = functoolsKit.singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$1);
+});
 const main$1 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
@@ -1927,7 +1943,7 @@ const main$1 = async () => {
     if (!values.ui) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$1);
+    listenGracefulShutdown$1();
 };
 main$1();
 
@@ -1936,6 +1952,9 @@ const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
     notifyShutdown();
     cli.telegramProviderService.disable();
 });
+const listenGracefulShutdown = functoolsKit.singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN);
+});
 const main = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
@@ -1944,7 +1963,7 @@ const main = async () => {
     if (!values.telegram) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN);
+    listenGracefulShutdown();
 };
 main();
 
@@ -1961,13 +1980,19 @@ async function run(mode, args) {
         _is_started = true;
     }
     if (mode === "backtest") {
-        return await cli.backtestMainService.run(args);
+        await cli.backtestMainService.run(args);
+        listenGracefulShutdown$4();
+        return;
     }
     if (mode === "paper") {
-        return await cli.paperMainService.run(args);
+        await cli.paperMainService.run(args);
+        listenGracefulShutdown$3();
+        return;
     }
     if (mode === "live") {
-        return await cli.liveMainService.run(args);
+        await cli.liveMainService.run(args);
+        listenGracefulShutdown$2();
+        return;
     }
     throw new Error(`Invalid mode: ${mode}`);
 }

package/build/index.mjs

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { Storage, Notification, Markdown, Report, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, listStrategySchema, overrideExchangeSchema, Backtest, Live, getCandles, checkCandles, warmCandles, listenRisk, listenSignal, listenStrategyCommit } from 'backtest-kit';
 import { getErrorMessage, errorData, singleshot, str, BehaviorSubject, compose, execpool, queued, sleep, randomString, createAwaiter, TIMEOUT_SYMBOL, typo, retry, memoize, trycatch } from 'functools-kit';
 import fs, { constants } from 'fs';
@@ -514,8 +515,8 @@ class BacktestMainService {
             });
             notifyFinish();
         });
-        this.init = singleshot(async () => {
-            this.loggerService.log("backtestMainService init");
+        this.connect = singleshot(async () => {
+            this.loggerService.log("backtestMainService connect");
             if (!getEntry(import.meta.url)) {
                 return;
             }
@@ -591,8 +592,8 @@ class LiveMainService {
             });
             notifyFinish();
         });
-        this.init = singleshot(async () => {
-            this.loggerService.log("liveMainService init");
+        this.connect = singleshot(async () => {
+            this.loggerService.log("liveMainService connect");
             if (!getEntry(import.meta.url)) {
                 return;
             }
@@ -661,8 +662,8 @@ class PaperMainService {
             });
             notifyFinish();
         });
-        this.init = singleshot(async () => {
-            this.loggerService.log("paperMainService init");
+        this.connect = singleshot(async () => {
+            this.loggerService.log("paperMainService connect");
             if (!getEntry(import.meta.url)) {
                 return;
             }
@@ -1823,6 +1824,9 @@ const BEFORE_EXIT_FN$4 = singleshot(async () => {
         frameName,
     });
 });
+const listenGracefulShutdown$4 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$4);
+});
 const main$4 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
@@ -1831,7 +1835,8 @@ const main$4 = async () => {
     if (!values.backtest) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$4);
+    await cli.backtestMainService.connect();
+    listenGracefulShutdown$4();
 };
 main$4();
 
@@ -1851,6 +1856,9 @@ const BEFORE_EXIT_FN$3 = singleshot(async () => {
         strategyName,
     });
 });
+const listenGracefulShutdown$3 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$3);
+});
 const main$3 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
@@ -1859,7 +1867,8 @@ const main$3 = async () => {
     if (!values.paper) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$3);
+    cli.paperMainService.connect();
+    listenGracefulShutdown$3();
 };
 main$3();
 
@@ -1880,6 +1889,9 @@ const BEFORE_EXIT_FN$2 = singleshot(async () => {
     });
     listenDoneLive(cli.liveProviderService.disable);
 });
+const listenGracefulShutdown$2 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$2);
+});
 const main$2 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
@@ -1888,7 +1900,8 @@ const main$2 = async () => {
     if (!values.live) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$2);
+    await cli.liveMainService.connect();
+    listenGracefulShutdown$2();
 };
 main$2();
 
@@ -1897,6 +1910,9 @@ const BEFORE_EXIT_FN$1 = singleshot(async () => {
     notifyShutdown();
     cli.frontendProviderService.disable();
 });
+const listenGracefulShutdown$1 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$1);
+});
 const main$1 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
@@ -1905,7 +1921,7 @@ const main$1 = async () => {
     if (!values.ui) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$1);
+    listenGracefulShutdown$1();
 };
 main$1();
 
@@ -1914,6 +1930,9 @@ const BEFORE_EXIT_FN = singleshot(async () => {
     notifyShutdown();
     cli.telegramProviderService.disable();
 });
+const listenGracefulShutdown = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN);
+});
 const main = async () => {
     if (!getEntry(import.meta.url)) {
         return;
@@ -1922,7 +1941,7 @@ const main = async () => {
     if (!values.telegram) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN);
+    listenGracefulShutdown();
 };
 main();
 
@@ -1939,13 +1958,19 @@ async function run(mode, args) {
         _is_started = true;
     }
     if (mode === "backtest") {
-        return await cli.backtestMainService.run(args);
+        await cli.backtestMainService.run(args);
+        listenGracefulShutdown$4();
+        return;
     }
     if (mode === "paper") {
-        return await cli.paperMainService.run(args);
+        await cli.paperMainService.run(args);
+        listenGracefulShutdown$3();
+        return;
     }
     if (mode === "live") {
-        return await cli.liveMainService.run(args);
+        await cli.liveMainService.run(args);
+        listenGracefulShutdown$2();
+        return;
     }
     throw new Error(`Invalid mode: ${mode}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtest-kit/cli",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "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",

package/types.d.ts

@@ -32,7 +32,7 @@ declare class PaperMainService {
         exchange: string;
         verbose: boolean;
     }) => Promise<void>) & functools_kit.ISingleshotClearable;
-    protected init: (() => Promise<void>) & functools_kit.ISingleshotClearable;
+    connect: (() => Promise<void>) & functools_kit.ISingleshotClearable;
 }
 
 declare class LiveMainService {
@@ -50,7 +50,7 @@ declare class LiveMainService {
         exchange: string;
         verbose: boolean;
     }) => Promise<void>) & functools_kit.ISingleshotClearable;
-    protected init: (() => Promise<void>) & functools_kit.ISingleshotClearable;
+    connect: (() => Promise<void>) & functools_kit.ISingleshotClearable;
 }
 
 declare class BacktestMainService {
@@ -71,7 +71,7 @@ declare class BacktestMainService {
         cacheList: string[];
         verbose: boolean;
     }) => Promise<void>) & functools_kit.ISingleshotClearable;
-    protected init: (() => Promise<void>) & functools_kit.ISingleshotClearable;
+    connect: (() => Promise<void>) & functools_kit.ISingleshotClearable;
 }
 
 declare class ExchangeSchemaService {