@backtest-kit/cli 5.10.1 → 5.10.2

package/README.md

@@ -613,6 +613,98 @@ Print to stdout (no flag):
 npx @backtest-kit/cli --pine ./math/impulse_trend_15m.pine
 ```
 
+## 💾 Dumping Raw Candles
+
+`@backtest-kit/cli` can fetch raw OHLCV candles from any registered exchange and save them to a file — no strategy file required.
+
+### CLI Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--dump` | boolean | Enable candle dump mode |
+| `--symbol` | string | Trading pair (default: `"BTCUSDT"`) |
+| `--timeframe` | string | Candle interval (default: `"15m"`) |
+| `--limit` | string | Number of candles to fetch (default: `250`) |
+| `--when` | string | End date for candle window — ISO 8601 or Unix ms (default: now) |
+| `--exchange` | string | Exchange name (default: first registered, falls back to CCXT Binance) |
+| `--output` | string | Output file base name without extension (default: `{SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP}`) |
+| `--json` | boolean | Write candles as a JSON array to `./dump/{output}.json` |
+| `--jsonl` | boolean | Write candles as JSONL (one row per line) to `./dump/{output}.jsonl` |
+
+The `dump/` directory is created in the current working directory (where the CLI is invoked from).
+
+### Exchange via `dump.module`
+
+By default the CLI registers CCXT Binance automatically. To use a different exchange — or to configure API keys, custom rate limits, or a non-spot market — create a `modules/dump.module.ts` file. The CLI loads it automatically before fetching candles.
+
+The CLI looks for `modules/dump.module` in the current working directory
+
+```
+my-project/
+├── modules/
+│   └── dump.module.ts            ← exchange registration
+├── dump/                         ← auto-created: candle output files
+└── package.json
+```
+
+Inside `dump.module.ts` call `addExchangeSchema` from `backtest-kit`:
+
+```typescript
+// modules/dump.module.ts
+import { addExchangeSchema } from "backtest-kit";
+import ccxt from "ccxt";
+
+addExchangeSchema({
+  exchangeName: "my-exchange",
+  getCandles: async (symbol, interval, since, limit) => {
+    const exchange = new ccxt.bybit({ enableRateLimit: true });
+    const ohlcv = await exchange.fetchOHLCV(symbol, interval, since.getTime(), limit);
+    return ohlcv.map(([timestamp, open, high, low, close, volume]) => ({
+      timestamp, open, high, low, close, volume,
+    }));
+  },
+  formatPrice: (symbol, price) => price.toFixed(2),
+  formatQuantity: (symbol, quantity) => quantity.toFixed(8),
+});
+```
+
+### Output
+
+Each candle row contains OHLCV fields. Print to stdout:
+
+```bash
+npx @backtest-kit/cli --dump --symbol BTCUSDT --timeframe 15m --limit 100
+```
+
+Save to `./dump/BTCUSDT_100_15m_{timestamp}.jsonl`:
+
+```bash
+npx @backtest-kit/cli --dump --symbol BTCUSDT --timeframe 15m --limit 100 --jsonl
+```
+
+Fetch candles up to a specific date with `--when` and override the file name with `--output`:
+
+```bash
+npx @backtest-kit/cli --dump --symbol BTCUSDT --timeframe 15m --limit 500 \
+  --when "2026-02-28T00:00:00.000Z" \
+  --jsonl --output feb2026_btc
+# → ./dump/feb2026_btc.jsonl
+```
+
+Or add it to `package.json`:
+
+```json
+{
+  "scripts": {
+    "dump": "npx @backtest-kit/cli --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl"
+  }
+}
+```
+
+```bash
+npx @backtest-kit/cli --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
+```
+
 ## 🌍 Environment Variables
 
 Create a `.env` file in your project root:

package/build/index.cjs

@@ -507,6 +507,10 @@ const getArgs = functoolsKit.singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            dump: {
+                type: "boolean",
+                default: false,
+            },
             timeframe: {
                 type: "string",
                 default: "",
@@ -2202,7 +2206,7 @@ const BEFORE_EXIT_FN$4 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$4 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$5 = async () => {
+const main$6 = 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;
     }
@@ -2213,7 +2217,7 @@ const main$5 = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$4();
 };
-main$5();
+main$6();
 
 const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -2234,7 +2238,7 @@ const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$3 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$4 = async () => {
+const main$5 = 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;
     }
@@ -2245,7 +2249,7 @@ const main$4 = async () => {
     cli.paperMainService.connect();
     listenGracefulShutdown$3();
 };
-main$4();
+main$5();
 
 const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$2);
@@ -2266,7 +2270,7 @@ const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$2 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$3 = async () => {
+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;
     }
@@ -2277,7 +2281,7 @@ const main$3 = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$2();
 };
-main$3();
+main$4();
 
 const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -2287,7 +2291,7 @@ const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$1 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$2 = async () => {
+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;
     }
@@ -2297,7 +2301,7 @@ const main$2 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$2();
+main$3();
 
 const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -2307,7 +2311,7 @@ const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$1 = async () => {
+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;
     }
@@ -2317,7 +2321,7 @@ const main$1 = async () => {
     }
     listenGracefulShutdown();
 };
-main$1();
+main$2();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -2339,7 +2343,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main = async () => {
+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;
     }
@@ -2388,23 +2392,76 @@ const main = async () => {
     const dumpDir = path.join(process.cwd(), "dump");
     if (values.json) {
         const rows = EXTRACT_ROWS_FN(plots, signalSchema);
+        const filePath = path.resolve(dumpDir, `${dumpName}.json`);
         await fs$1.mkdir(dumpDir, { recursive: true });
-        await fs$1.writeFile(path.join(dumpDir, `${dumpName}.json`), JSON.stringify(rows, null, 2), "utf-8");
+        await fs$1.writeFile(filePath, JSON.stringify(rows, null, 2), "utf-8");
+        console.log(`Saved: ${filePath}`);
         return;
     }
     if (values.jsonl) {
         const rows = EXTRACT_ROWS_FN(plots, signalSchema);
+        const filePath = path.resolve(dumpDir, `${dumpName}.jsonl`);
         await fs$1.mkdir(dumpDir, { recursive: true });
-        await fs$1.writeFile(path.join(dumpDir, `${dumpName}.jsonl`), rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
+        await fs$1.writeFile(filePath, rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
+        console.log(`Saved: ${filePath}`);
         return;
     }
     if (values.markdown) {
+        const filePath = path.resolve(dumpDir, `${dumpName}.md`);
         await fs$1.mkdir(dumpDir, { recursive: true });
-        await fs$1.writeFile(path.join(dumpDir, `${dumpName}.md`), await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema), "utf-8");
+        await fs$1.writeFile(filePath, await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema), "utf-8");
+        console.log(`Saved: ${filePath}`);
         return;
     }
     console.log(await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema));
 };
+main$1();
+
+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;
+    }
+    const { values } = getArgs();
+    if (!values.dump) {
+        return;
+    }
+    await cli.moduleConnectionService.loadModule("./dump.module");
+    {
+        await cli.exchangeSchemaService.addSchema();
+        await cli.symbolSchemaService.addSchema();
+    }
+    const [defaultExchangeName = null] = await BacktestKit.listExchangeSchema();
+    const exchangeName = values.exchange || defaultExchangeName?.exchangeName;
+    const symbol = values.symbol || "BTCUSDT";
+    const timeframe = values.timeframe || "15m";
+    const limitStr = values.limit || "250";
+    const limitNum = parseInt(limitStr);
+    const limit = isNaN(limitNum) ? 250 : limitNum;
+    const whenStr = values.when || Date.now().toString();
+    const whenStamp = Date.parse(whenStr);
+    const when = isNaN(whenStamp) ? new Date() : new Date(whenStamp);
+    const timestamp = BacktestKit.alignToInterval(when, timeframe).getTime();
+    const candles = await BacktestKit.Exchange.getRawCandles(symbol, timeframe, {
+        exchangeName,
+    }, limit, undefined, timestamp);
+    const dumpName = values.output || `${symbol}_${limit}_${timeframe}_${timestamp}`;
+    const dumpDir = path.join(process.cwd(), "dump");
+    if (values.json) {
+        const filePath = path.resolve(dumpDir, `${dumpName}.json`);
+        await fs$1.mkdir(dumpDir, { recursive: true });
+        await fs$1.writeFile(filePath, JSON.stringify(candles, null, 2), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        return;
+    }
+    if (values.jsonl) {
+        const filePath = path.resolve(dumpDir, `${dumpName}.jsonl`);
+        await fs$1.mkdir(dumpDir, { recursive: true });
+        await fs$1.writeFile(filePath, candles.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        return;
+    }
+    console.log(JSON.stringify(candles, null, 2));
+};
 main();
 
 function setLogger(logger) {

package/build/index.mjs

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import * as BacktestKit from 'backtest-kit';
-import { Storage, Notification, Markdown, Report, Dump, Memory, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, setConfig, Log, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, shutdown, listenSignal, listStrategySchema, overrideExchangeSchema, Backtest, Live, getCandles, checkCandles, warmCandles, listenRisk, listenStrategyCommit, listenSync } from 'backtest-kit';
+import { Storage, Notification, Markdown, Report, Dump, Memory, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, setConfig, Log, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, shutdown, listenSignal, listStrategySchema, overrideExchangeSchema, Backtest, Live, getCandles, checkCandles, warmCandles, listenRisk, listenStrategyCommit, listenSync, alignToInterval, Exchange } from 'backtest-kit';
 import { getErrorMessage, errorData, singleshot, str, BehaviorSubject, compose, execpool, queued, sleep, randomString, createAwaiter, TIMEOUT_SYMBOL, typo, retry, trycatch, memoize } from 'functools-kit';
 import fs, { constants } from 'fs';
 import * as stackTrace from 'stack-trace';
-import path, { basename, extname, join } from 'path';
+import path, { basename, extname, join, resolve } from 'path';
 import fs$1, { access, readFile, mkdir, writeFile } from 'fs/promises';
 import dotenv from 'dotenv';
 import { createActivator } from 'di-kit';
@@ -482,6 +482,10 @@ const getArgs = singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            dump: {
+                type: "boolean",
+                default: false,
+            },
             timeframe: {
                 type: "string",
                 default: "",
@@ -2173,7 +2177,7 @@ const BEFORE_EXIT_FN$4 = singleshot(async () => {
 const listenGracefulShutdown$4 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$5 = async () => {
+const main$6 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2184,7 +2188,7 @@ const main$5 = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$4();
 };
-main$5();
+main$6();
 
 const BEFORE_EXIT_FN$3 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -2205,7 +2209,7 @@ const BEFORE_EXIT_FN$3 = singleshot(async () => {
 const listenGracefulShutdown$3 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$4 = async () => {
+const main$5 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2216,7 +2220,7 @@ const main$4 = async () => {
     cli.paperMainService.connect();
     listenGracefulShutdown$3();
 };
-main$4();
+main$5();
 
 const BEFORE_EXIT_FN$2 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$2);
@@ -2237,7 +2241,7 @@ const BEFORE_EXIT_FN$2 = singleshot(async () => {
 const listenGracefulShutdown$2 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$3 = async () => {
+const main$4 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2248,7 +2252,7 @@ const main$3 = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$2();
 };
-main$3();
+main$4();
 
 const BEFORE_EXIT_FN$1 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -2258,7 +2262,7 @@ const BEFORE_EXIT_FN$1 = singleshot(async () => {
 const listenGracefulShutdown$1 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$2 = async () => {
+const main$3 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2268,7 +2272,7 @@ const main$2 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$2();
+main$3();
 
 const BEFORE_EXIT_FN = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -2278,7 +2282,7 @@ const BEFORE_EXIT_FN = singleshot(async () => {
 const listenGracefulShutdown = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$1 = async () => {
+const main$2 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2288,7 +2292,7 @@ const main$1 = async () => {
     }
     listenGracefulShutdown();
 };
-main$1();
+main$2();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -2310,7 +2314,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main = async () => {
+const main$1 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2359,23 +2363,76 @@ const main = async () => {
     const dumpDir = join(process.cwd(), "dump");
     if (values.json) {
         const rows = EXTRACT_ROWS_FN(plots, signalSchema);
+        const filePath = resolve(dumpDir, `${dumpName}.json`);
         await mkdir(dumpDir, { recursive: true });
-        await writeFile(join(dumpDir, `${dumpName}.json`), JSON.stringify(rows, null, 2), "utf-8");
+        await writeFile(filePath, JSON.stringify(rows, null, 2), "utf-8");
+        console.log(`Saved: ${filePath}`);
         return;
     }
     if (values.jsonl) {
         const rows = EXTRACT_ROWS_FN(plots, signalSchema);
+        const filePath = resolve(dumpDir, `${dumpName}.jsonl`);
         await mkdir(dumpDir, { recursive: true });
-        await writeFile(join(dumpDir, `${dumpName}.jsonl`), rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
+        await writeFile(filePath, rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
+        console.log(`Saved: ${filePath}`);
         return;
     }
     if (values.markdown) {
+        const filePath = resolve(dumpDir, `${dumpName}.md`);
         await mkdir(dumpDir, { recursive: true });
-        await writeFile(join(dumpDir, `${dumpName}.md`), await toMarkdown(signalId, plots, signalSchema), "utf-8");
+        await writeFile(filePath, await toMarkdown(signalId, plots, signalSchema), "utf-8");
+        console.log(`Saved: ${filePath}`);
         return;
     }
     console.log(await toMarkdown(signalId, plots, signalSchema));
 };
+main$1();
+
+const main = async () => {
+    if (!getEntry(import.meta.url)) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.dump) {
+        return;
+    }
+    await cli.moduleConnectionService.loadModule("./dump.module");
+    {
+        await cli.exchangeSchemaService.addSchema();
+        await cli.symbolSchemaService.addSchema();
+    }
+    const [defaultExchangeName = null] = await listExchangeSchema();
+    const exchangeName = values.exchange || defaultExchangeName?.exchangeName;
+    const symbol = values.symbol || "BTCUSDT";
+    const timeframe = values.timeframe || "15m";
+    const limitStr = values.limit || "250";
+    const limitNum = parseInt(limitStr);
+    const limit = isNaN(limitNum) ? 250 : limitNum;
+    const whenStr = values.when || Date.now().toString();
+    const whenStamp = Date.parse(whenStr);
+    const when = isNaN(whenStamp) ? new Date() : new Date(whenStamp);
+    const timestamp = alignToInterval(when, timeframe).getTime();
+    const candles = await Exchange.getRawCandles(symbol, timeframe, {
+        exchangeName,
+    }, limit, undefined, timestamp);
+    const dumpName = values.output || `${symbol}_${limit}_${timeframe}_${timestamp}`;
+    const dumpDir = join(process.cwd(), "dump");
+    if (values.json) {
+        const filePath = resolve(dumpDir, `${dumpName}.json`);
+        await mkdir(dumpDir, { recursive: true });
+        await writeFile(filePath, JSON.stringify(candles, null, 2), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        return;
+    }
+    if (values.jsonl) {
+        const filePath = resolve(dumpDir, `${dumpName}.jsonl`);
+        await mkdir(dumpDir, { recursive: true });
+        await writeFile(filePath, candles.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
+        console.log(`Saved: ${filePath}`);
+        return;
+    }
+    console.log(JSON.stringify(candles, null, 2));
+};
 main();
 
 function setLogger(logger) {

package/package.json

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