@backtest-kit/cli 0.0.2 → 0.0.3

package/README.md

@@ -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   |
+| Flag          | 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

@@ -536,8 +536,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 +613,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 +683,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 +1845,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 +1856,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 +1877,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 +1888,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 +1910,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 +1921,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 +1931,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 +1942,7 @@ const main$1 = async () => {
     if (!values.ui) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$1);
+    listenGracefulShutdown$1();
 };
 main$1();
 
@@ -1936,6 +1951,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 +1962,7 @@ const main = async () => {
     if (!values.telegram) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN);
+    listenGracefulShutdown();
 };
 main();
 
@@ -1961,13 +1979,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

@@ -514,8 +514,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 +591,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 +661,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 +1823,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 +1834,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 +1855,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 +1866,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 +1888,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 +1899,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 +1909,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 +1920,7 @@ const main$1 = async () => {
     if (!values.ui) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN$1);
+    listenGracefulShutdown$1();
 };
 main$1();
 
@@ -1914,6 +1929,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 +1940,7 @@ const main = async () => {
     if (!values.telegram) {
         return;
     }
-    process.on("SIGINT", BEFORE_EXIT_FN);
+    listenGracefulShutdown();
 };
 main();
 
@@ -1939,13 +1957,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.3",
   "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 {