@backtest-kit/cli 5.11.1 → 6.0.0

package/build/index.cjs

@@ -557,6 +557,14 @@ const getArgs = functoolsKit.singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            help: {
+                type: "boolean",
+                default: false,
+            },
+            version: {
+                type: "boolean",
+                default: false,
+            },
         },
         strict: false,
         allowPositionals: true,
@@ -2231,7 +2239,7 @@ const BEFORE_EXIT_FN$4 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$4 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$7 = async () => {
+const main$9 = 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;
     }
@@ -2242,7 +2250,7 @@ const main$7 = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$4();
 };
-main$7();
+main$9();
 
 const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -2263,7 +2271,7 @@ const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$3 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$6 = async () => {
+const main$8 = 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;
     }
@@ -2274,7 +2282,7 @@ const main$6 = async () => {
     cli.paperMainService.connect();
     listenGracefulShutdown$3();
 };
-main$6();
+main$8();
 
 const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$2);
@@ -2295,7 +2303,7 @@ const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$2 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$5 = async () => {
+const main$7 = 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;
     }
@@ -2306,7 +2314,7 @@ const main$5 = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$2();
 };
-main$5();
+main$7();
 
 const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -2316,7 +2324,7 @@ const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$1 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$4 = 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;
     }
@@ -2326,7 +2334,7 @@ const main$4 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$4();
+main$6();
 
 const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -2336,7 +2344,7 @@ const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$3 = 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;
     }
@@ -2346,7 +2354,7 @@ const main$3 = async () => {
     }
     listenGracefulShutdown();
 };
-main$3();
+main$5();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -2368,7 +2376,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main$2 = 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;
     }
@@ -2421,6 +2429,7 @@ const main$2 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, JSON.stringify(rows, null, 2), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.jsonl) {
@@ -2429,6 +2438,7 @@ const main$2 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.markdown) {
@@ -2436,13 +2446,15 @@ const main$2 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     console.log(await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema));
+    process.exit(0);
 };
-main$2();
+main$4();
 
-const main$1 = 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;
     }
@@ -2476,6 +2488,7 @@ const main$1 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, JSON.stringify(candles, null, 2), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.jsonl) {
@@ -2483,15 +2496,21 @@ const main$1 = async () => {
         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}`);
+        process.exit(0);
         return;
     }
     console.log(JSON.stringify(candles, null, 2));
+    process.exit(0);
 };
-main$1();
+main$3();
 
 const __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
 const __dirname$1 = path.dirname(__filename$1);
 const MUSTACHE_EXT = ".mustache";
+const MUSTACHE_RENAME = {
+    "gitignore": ".gitignore",
+    "package": "package.json",
+};
 async function isDirEmpty(dirPath) {
     try {
         const files = await fs$1.readdir(dirPath);
@@ -2513,8 +2532,12 @@ async function copyDir(srcDir, destDir, data) {
             await copyDir(srcPath, path.join(destDir, entry.name), data);
             continue;
         }
+        if (entry.name === ".gitkeep") {
+            continue;
+        }
         if (entry.name.endsWith(MUSTACHE_EXT)) {
-            const destName = entry.name.slice(0, -MUSTACHE_EXT.length);
+            const baseName = entry.name.slice(0, -MUSTACHE_EXT.length);
+            const destName = MUSTACHE_RENAME[baseName] ?? baseName;
             const destPath = path.join(destDir, destName);
             const template = await fs$1.readFile(srcPath, "utf-8");
             const rendered = Mustache.render(template, data);
@@ -2542,7 +2565,7 @@ function runScript(scriptPath, cwd) {
         child.on("error", reject);
     });
 }
-const main = 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;
     }
@@ -2552,7 +2575,7 @@ const main = async () => {
     }
     const projectName = values.output || "backtest-kit-project";
     const projectPath = path.join(process.cwd(), projectName);
-    const templatePath = path.join(__dirname$1, "../../template/project");
+    const templatePath = path.join(__dirname$1, "../template/project");
     const isEmpty = await isDirEmpty(projectPath);
     if (!isEmpty) {
         console.error(`Directory "${projectName}" already exists and is not empty.`);
@@ -2563,6 +2586,131 @@ const main = async () => {
     console.log(`Fetching docs...`);
     await runScript(path.join(projectPath, "scripts/fetch_docs.mjs"), projectPath);
     console.log(`Done! Project created at ${projectPath}`);
+    process.exit(0);
+};
+main$2();
+
+const HELP_TEXT = `
+@backtest-kit/cli
+
+Usage:
+  node index.mjs --<mode> [flags] [entry-point]
+
+Modes:
+
+  --backtest <entry>    Run strategy against historical candle data
+  --paper    <entry>    Paper trading (live prices, no real orders)
+  --live     <entry>    Live trading with real orders
+  --pine     <entry>    Execute a local .pine indicator file
+  --dump                Fetch and save raw OHLCV candles
+  --init                Scaffold a new project in the current directory
+  --help                Print this help message
+
+Backtest flags:
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --strategy    <string>   Strategy name from addStrategySchema (default: first registered)
+  --exchange    <string>   Exchange name from addExchangeSchema (default: first registered)
+  --frame       <string>   Frame name from addFrameSchema (default: first registered)
+  --cacheInterval <string> Comma-separated intervals to pre-cache (default: "1m, 15m, 30m, 4h")
+  --noCache                Skip candle cache warming before the run
+  --verbose                Log every candle fetch to stdout
+  --ui                     Start web dashboard at http://localhost:60050
+  --telegram               Send trade notifications to Telegram
+
+Paper / Live flags:
+
+  --symbol    <string>   Trading pair (default: BTCUSDT)
+  --strategy  <string>   Strategy name (default: first registered)
+  --exchange  <string>   Exchange name (default: first registered)
+  --verbose              Log every candle fetch to stdout
+  --ui                   Start web dashboard
+  --telegram             Send Telegram notifications
+
+PineScript flags (--pine):
+
+  --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 — ISO 8601 or Unix ms (default: now)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name without extension
+  --json                   Save output as JSON array to <pine-dir>/dump/<output>.json
+  --jsonl                  Save output as JSONL to <pine-dir>/dump/<output>.jsonl
+  --markdown               Save output as Markdown table to <pine-dir>/dump/<output>.md
+
+  Only plot() calls with display=display.data_window produce output columns.
+  Module file ./modules/pine.module is loaded automatically if it exists.
+
+Candle dump flags (--dump):
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --timeframe   <string>   Candle interval (default: 15m)
+  --limit       <string>   Number of candles (default: 250)
+  --when        <string>   End date — ISO 8601 or Unix ms (default: now)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name (default: {SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP})
+  --json                   Save as JSON array to ./dump/<output>.json
+  --jsonl                  Save as JSONL to ./dump/<output>.jsonl
+
+  Module file ./modules/dump.module is loaded automatically if it exists.
+
+Init flags (--init):
+
+  --output <string>   Target directory name (default: backtest-kit-project)
+
+  Scaffolds a project and runs scripts/fetch_docs.mjs to download library docs.
+
+Module hooks (loaded automatically by each mode):
+
+  modules/backtest.module   --backtest   Broker adapter for backtest
+  modules/paper.module      --paper      Broker adapter for paper trading
+  modules/live.module       --live       Broker adapter for live trading
+  modules/pine.module       --pine       Exchange schema for PineScript runs
+  modules/dump.module       --dump       Exchange schema for candle dumps
+
+  Extensions .ts, .mjs, .cjs are tried automatically. Missing module = soft warning.
+
+Environment variables:
+
+  CC_TELEGRAM_TOKEN    Telegram bot token (required for --telegram)
+  CC_TELEGRAM_CHANNEL  Telegram channel or chat ID (required for --telegram)
+  CC_WWWROOT_HOST      UI server bind address (default: 0.0.0.0)
+  CC_WWWROOT_PORT      UI server port (default: 60050)
+
+Examples:
+
+  node index.mjs --backtest ./content/feb_2026.strategy.ts
+  node index.mjs --backtest --symbol BTCUSDT --noCache --ui ./content/feb_2026.strategy.ts
+  node index.mjs --paper --symbol ETHUSDT ./content/feb_2026.strategy.ts
+  node index.mjs --live --ui --telegram ./content/feb_2026.strategy.ts
+  node index.mjs --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --jsonl
+  node index.mjs --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
+  node index.mjs --init --output my-trading-bot
+`.trimStart();
+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;
+    }
+    const { values } = getArgs();
+    if (!values.help) {
+        return;
+    }
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+};
+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.version) {
+        return;
+    }
+    process.stdout.write(`@backtest-kit/cli ${"6.0.0"}\n`);
+    process.exit(0);
 };
 main();
 

package/build/index.mjs

@@ -532,6 +532,14 @@ const getArgs = singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            help: {
+                type: "boolean",
+                default: false,
+            },
+            version: {
+                type: "boolean",
+                default: false,
+            },
         },
         strict: false,
         allowPositionals: true,
@@ -2202,7 +2210,7 @@ const BEFORE_EXIT_FN$4 = singleshot(async () => {
 const listenGracefulShutdown$4 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$7 = async () => {
+const main$9 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2213,7 +2221,7 @@ const main$7 = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$4();
 };
-main$7();
+main$9();
 
 const BEFORE_EXIT_FN$3 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -2234,7 +2242,7 @@ const BEFORE_EXIT_FN$3 = singleshot(async () => {
 const listenGracefulShutdown$3 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$6 = async () => {
+const main$8 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2245,7 +2253,7 @@ const main$6 = async () => {
     cli.paperMainService.connect();
     listenGracefulShutdown$3();
 };
-main$6();
+main$8();
 
 const BEFORE_EXIT_FN$2 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$2);
@@ -2266,7 +2274,7 @@ const BEFORE_EXIT_FN$2 = singleshot(async () => {
 const listenGracefulShutdown$2 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$5 = async () => {
+const main$7 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2277,7 +2285,7 @@ const main$5 = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$2();
 };
-main$5();
+main$7();
 
 const BEFORE_EXIT_FN$1 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -2287,7 +2295,7 @@ const BEFORE_EXIT_FN$1 = singleshot(async () => {
 const listenGracefulShutdown$1 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$4 = async () => {
+const main$6 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2297,7 +2305,7 @@ const main$4 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$4();
+main$6();
 
 const BEFORE_EXIT_FN = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -2307,7 +2315,7 @@ const BEFORE_EXIT_FN = singleshot(async () => {
 const listenGracefulShutdown = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$3 = async () => {
+const main$5 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2317,7 +2325,7 @@ const main$3 = async () => {
     }
     listenGracefulShutdown();
 };
-main$3();
+main$5();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -2339,7 +2347,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main$2 = async () => {
+const main$4 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2392,6 +2400,7 @@ const main$2 = async () => {
         await mkdir(dumpDir, { recursive: true });
         await writeFile(filePath, JSON.stringify(rows, null, 2), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.jsonl) {
@@ -2400,6 +2409,7 @@ const main$2 = async () => {
         await mkdir(dumpDir, { recursive: true });
         await writeFile(filePath, rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.markdown) {
@@ -2407,13 +2417,15 @@ const main$2 = async () => {
         await mkdir(dumpDir, { recursive: true });
         await writeFile(filePath, await toMarkdown(signalId, plots, signalSchema), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     console.log(await toMarkdown(signalId, plots, signalSchema));
+    process.exit(0);
 };
-main$2();
+main$4();
 
-const main$1 = async () => {
+const main$3 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2447,6 +2459,7 @@ const main$1 = async () => {
         await mkdir(dumpDir, { recursive: true });
         await writeFile(filePath, JSON.stringify(candles, null, 2), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.jsonl) {
@@ -2454,15 +2467,21 @@ const main$1 = async () => {
         await mkdir(dumpDir, { recursive: true });
         await writeFile(filePath, candles.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     console.log(JSON.stringify(candles, null, 2));
+    process.exit(0);
 };
-main$1();
+main$3();
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const MUSTACHE_EXT = ".mustache";
+const MUSTACHE_RENAME = {
+    "gitignore": ".gitignore",
+    "package": "package.json",
+};
 async function isDirEmpty(dirPath) {
     try {
         const files = await readdir(dirPath);
@@ -2484,8 +2503,12 @@ async function copyDir(srcDir, destDir, data) {
             await copyDir(srcPath, join(destDir, entry.name), data);
             continue;
         }
+        if (entry.name === ".gitkeep") {
+            continue;
+        }
         if (entry.name.endsWith(MUSTACHE_EXT)) {
-            const destName = entry.name.slice(0, -MUSTACHE_EXT.length);
+            const baseName = entry.name.slice(0, -MUSTACHE_EXT.length);
+            const destName = MUSTACHE_RENAME[baseName] ?? baseName;
             const destPath = join(destDir, destName);
             const template = await readFile(srcPath, "utf-8");
             const rendered = Mustache.render(template, data);
@@ -2513,7 +2536,7 @@ function runScript(scriptPath, cwd) {
         child.on("error", reject);
     });
 }
-const main = async () => {
+const main$2 = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -2523,7 +2546,7 @@ const main = async () => {
     }
     const projectName = values.output || "backtest-kit-project";
     const projectPath = join(process.cwd(), projectName);
-    const templatePath = join(__dirname, "../../template/project");
+    const templatePath = join(__dirname, "../template/project");
     const isEmpty = await isDirEmpty(projectPath);
     if (!isEmpty) {
         console.error(`Directory "${projectName}" already exists and is not empty.`);
@@ -2534,6 +2557,131 @@ const main = async () => {
     console.log(`Fetching docs...`);
     await runScript(join(projectPath, "scripts/fetch_docs.mjs"), projectPath);
     console.log(`Done! Project created at ${projectPath}`);
+    process.exit(0);
+};
+main$2();
+
+const HELP_TEXT = `
+@backtest-kit/cli
+
+Usage:
+  node index.mjs --<mode> [flags] [entry-point]
+
+Modes:
+
+  --backtest <entry>    Run strategy against historical candle data
+  --paper    <entry>    Paper trading (live prices, no real orders)
+  --live     <entry>    Live trading with real orders
+  --pine     <entry>    Execute a local .pine indicator file
+  --dump                Fetch and save raw OHLCV candles
+  --init                Scaffold a new project in the current directory
+  --help                Print this help message
+
+Backtest flags:
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --strategy    <string>   Strategy name from addStrategySchema (default: first registered)
+  --exchange    <string>   Exchange name from addExchangeSchema (default: first registered)
+  --frame       <string>   Frame name from addFrameSchema (default: first registered)
+  --cacheInterval <string> Comma-separated intervals to pre-cache (default: "1m, 15m, 30m, 4h")
+  --noCache                Skip candle cache warming before the run
+  --verbose                Log every candle fetch to stdout
+  --ui                     Start web dashboard at http://localhost:60050
+  --telegram               Send trade notifications to Telegram
+
+Paper / Live flags:
+
+  --symbol    <string>   Trading pair (default: BTCUSDT)
+  --strategy  <string>   Strategy name (default: first registered)
+  --exchange  <string>   Exchange name (default: first registered)
+  --verbose              Log every candle fetch to stdout
+  --ui                   Start web dashboard
+  --telegram             Send Telegram notifications
+
+PineScript flags (--pine):
+
+  --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 — ISO 8601 or Unix ms (default: now)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name without extension
+  --json                   Save output as JSON array to <pine-dir>/dump/<output>.json
+  --jsonl                  Save output as JSONL to <pine-dir>/dump/<output>.jsonl
+  --markdown               Save output as Markdown table to <pine-dir>/dump/<output>.md
+
+  Only plot() calls with display=display.data_window produce output columns.
+  Module file ./modules/pine.module is loaded automatically if it exists.
+
+Candle dump flags (--dump):
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --timeframe   <string>   Candle interval (default: 15m)
+  --limit       <string>   Number of candles (default: 250)
+  --when        <string>   End date — ISO 8601 or Unix ms (default: now)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name (default: {SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP})
+  --json                   Save as JSON array to ./dump/<output>.json
+  --jsonl                  Save as JSONL to ./dump/<output>.jsonl
+
+  Module file ./modules/dump.module is loaded automatically if it exists.
+
+Init flags (--init):
+
+  --output <string>   Target directory name (default: backtest-kit-project)
+
+  Scaffolds a project and runs scripts/fetch_docs.mjs to download library docs.
+
+Module hooks (loaded automatically by each mode):
+
+  modules/backtest.module   --backtest   Broker adapter for backtest
+  modules/paper.module      --paper      Broker adapter for paper trading
+  modules/live.module       --live       Broker adapter for live trading
+  modules/pine.module       --pine       Exchange schema for PineScript runs
+  modules/dump.module       --dump       Exchange schema for candle dumps
+
+  Extensions .ts, .mjs, .cjs are tried automatically. Missing module = soft warning.
+
+Environment variables:
+
+  CC_TELEGRAM_TOKEN    Telegram bot token (required for --telegram)
+  CC_TELEGRAM_CHANNEL  Telegram channel or chat ID (required for --telegram)
+  CC_WWWROOT_HOST      UI server bind address (default: 0.0.0.0)
+  CC_WWWROOT_PORT      UI server port (default: 60050)
+
+Examples:
+
+  node index.mjs --backtest ./content/feb_2026.strategy.ts
+  node index.mjs --backtest --symbol BTCUSDT --noCache --ui ./content/feb_2026.strategy.ts
+  node index.mjs --paper --symbol ETHUSDT ./content/feb_2026.strategy.ts
+  node index.mjs --live --ui --telegram ./content/feb_2026.strategy.ts
+  node index.mjs --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --jsonl
+  node index.mjs --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
+  node index.mjs --init --output my-trading-bot
+`.trimStart();
+const main$1 = async () => {
+    if (!getEntry(import.meta.url)) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.help) {
+        return;
+    }
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+};
+main$1();
+
+const main = async () => {
+    if (!getEntry(import.meta.url)) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.version) {
+        return;
+    }
+    process.stdout.write(`@backtest-kit/cli ${"6.0.0"}\n`);
+    process.exit(0);
 };
 main();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtest-kit/cli",
-  "version": "5.11.1",
+  "version": "6.0.0",
   "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",
@@ -61,11 +61,11 @@
   "devDependencies": {
     "@babel/plugin-transform-modules-umd": "7.27.1",
     "@babel/standalone": "7.29.1",
-    "@backtest-kit/ui": "5.11.0",
-    "@backtest-kit/graph": "5.11.0",
-    "@backtest-kit/ollama": "5.11.0",
-    "@backtest-kit/pinets": "5.11.0",
-    "@backtest-kit/signals": "5.11.0",
+    "@backtest-kit/ui": "6.0.0",
+    "@backtest-kit/graph": "6.0.0",
+    "@backtest-kit/ollama": "6.0.0",
+    "@backtest-kit/pinets": "6.0.0",
+    "@backtest-kit/signals": "6.0.0",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-typescript": "11.1.6",
     "@types/image-size": "0.7.0",
@@ -73,7 +73,7 @@
     "@types/mustache": "4.2.6",
     "@types/node": "22.9.0",
     "@types/stack-trace": "0.0.33",
-    "backtest-kit": "5.11.0",
+    "backtest-kit": "6.0.0",
     "glob": "11.0.1",
     "markdown-it": "14.1.1",
     "rimraf": "6.0.1",
@@ -88,12 +88,12 @@
   "peerDependencies": {
     "@babel/plugin-transform-modules-umd": "^7.27.1",
     "@babel/standalone": "^7.29.1",
-    "@backtest-kit/ui": "^5.11.0",
-    "@backtest-kit/graph": "^5.11.0",
-    "@backtest-kit/ollama": "^5.11.0",
-    "@backtest-kit/pinets": "^5.11.0",
-    "@backtest-kit/signals": "^5.11.0",
-    "backtest-kit": "^5.11.0",
+    "@backtest-kit/ui": "^6.0.0",
+    "@backtest-kit/graph": "^6.0.0",
+    "@backtest-kit/ollama": "^6.0.0",
+    "@backtest-kit/pinets": "^6.0.0",
+    "@backtest-kit/signals": "^6.0.0",
+    "backtest-kit": "^6.0.0",
     "markdown-it": "^14.1.1",
     "typescript": "^5.0.0"
   },

package/template/project/README.md

@@ -0,0 +1,207 @@
+# 🧿 Backtest Kit Project
+
+> 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)]()
+[![Build](https://github.com/tripolskypetr/backtest-kit/actions/workflows/webpack.yml/badge.svg)](https://github.com/tripolskypetr/backtest-kit/actions/workflows/webpack.yml)
+
+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.
+
+## 📋 Quick Start
+
+```bash
+npm start         # Run the CLI (append flags below)
+npm run sync:lib  # Refresh library docs in docs/lib/
+```
+
+## 🏃 Running Modes
+
+All modes are invoked via `npm start -- <flags> <entry-point>`.
+
+### 🧪 Backtest
+
+Runs the strategy against historical candle data defined by a `FrameSchema`.
+
+```bash
+npm start -- --backtest --symbol BTCUSDT --strategy feb_2026_strategy --exchange ccxt-exchange --frame feb_2026_frame ./content/feb_2026.strategy.ts
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--backtest` | boolean | — | Enable backtest mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--strategy` | string | first registered | Strategy name from `addStrategySchema` |
+| `--exchange` | string | first registered | Exchange name from `addExchangeSchema` |
+| `--frame` | string | first registered | Frame name from `addFrameSchema` |
+| `--cacheInterval` | string | `1m, 15m, 30m, 1h, 4h` | Comma-separated intervals to pre-cache before the run |
+| `--noCache` | boolean | `false` | Skip candle cache warming |
+| `--verbose` | boolean | `false` | Log every candle fetch to stdout |
+| `--ui` | boolean | `false` | Start web dashboard at `http://localhost:60050` |
+| `--telegram` | boolean | `false` | Send trade notifications to Telegram |
+
+Before the backtest starts, the CLI warms the candle cache for every interval in `--cacheInterval`. On subsequent runs the cache is used directly — no extra API calls. Pass `--noCache` to skip this step.
+
+Module file `./modules/backtest.module.ts` (or `.mjs`) is loaded automatically if it exists.
+
+### 📄 Paper Trading
+
+Connects to the live exchange but places no real orders. Identical code path to `--live` — safe for strategy validation.
+
+```bash
+npm start -- --paper --symbol BTCUSDT --strategy feb_2026_strategy --exchange ccxt-exchange ./content/feb_2026.strategy.ts
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--paper` | boolean | — | Enable paper trading mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--strategy` | string | first registered | Strategy name |
+| `--exchange` | string | first registered | Exchange name |
+| `--verbose` | boolean | `false` | Log every candle fetch to stdout |
+| `--ui` | boolean | `false` | Start web dashboard |
+| `--telegram` | boolean | `false` | Enable Telegram notifications |
+
+Module file `./modules/paper.module.ts` is loaded automatically if it exists.
+
+### 📈 Live Trading
+
+Deploys a real trading bot. Requires exchange API keys in `.env`.
+
+```bash
+npm start -- --live --symbol BTCUSDT --ui --telegram ./content/feb_2026.strategy.ts
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--live` | boolean | — | Enable live trading mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--strategy` | string | first registered | Strategy name |
+| `--exchange` | string | first registered | Exchange name |
+| `--verbose` | boolean | `false` | Log every candle fetch to stdout |
+| `--ui` | boolean | `false` | Start web dashboard |
+| `--telegram` | boolean | `false` | Enable Telegram notifications |
+
+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.
+
+## 🌲 Running PineScript Indicators (`--pine`)
+
+Executes a local `.pine` file against a real exchange and prints the output as a Markdown table or saves it to a file.
+
+```bash
+npm start -- --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --when "2026-02-28T00:00:00.000Z" --jsonl
+```
+
+Output file is created at `./math/dump/<name>.jsonl` (next to the `.pine` file).
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--pine` | boolean | — | Enable PineScript execution mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--timeframe` | string | `15m` | Candle interval |
+| `--limit` | string | `250` | Number of candles to fetch |
+| `--when` | string | now | End date — ISO 8601 or Unix ms |
+| `--exchange` | string | first registered | Exchange name |
+| `--output` | string | `.pine` file name | Output file base name (no extension) |
+| `--json` | boolean | `false` | Save output as JSON array |
+| `--jsonl` | boolean | `false` | Save output as JSONL (one row per line) |
+| `--markdown` | boolean | `false` | Save output as Markdown table |
+
+Module file `./modules/pine.module.ts` is loaded automatically. The project includes it pre-configured with CCXT Binance. Override it to use a different exchange.
+
+Only `plot()` calls with `display=display.data_window` produce output columns:
+
+```pine
+plot(close,    "Close",    display=display.data_window)
+plot(position, "Position", display=display.data_window)
+```
+
+## 💾 Dumping Raw Candles (`--dump`)
+
+Fetches raw OHLCV candles from an exchange and saves them to a file.
+
+```bash
+npm start -- --dump --timeframe 15m --limit 500 --when "2026-02-28T00:00:00.000Z" --jsonl
+```
+
+Output file is created at `./dump/<name>.jsonl`.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--dump` | boolean | — | Enable candle dump mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--timeframe` | string | `15m` | Candle interval |
+| `--limit` | string | `250` | Number of candles |
+| `--when` | string | now | End date — ISO 8601 or Unix ms |
+| `--exchange` | string | first registered | Exchange name |
+| `--output` | string | `{SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP}` | Output file base name |
+| `--json` | boolean | `false` | Save as JSON array |
+| `--jsonl` | boolean | `false` | Save as JSONL |
+
+Module file `./modules/dump.module.ts` is loaded automatically. The project includes it pre-configured with CCXT Binance.
+
+## 🧩 Module Hooks
+
+| File | Loaded by mode | Purpose |
+|------|----------------|---------|
+| `modules/backtest.module.ts` | `--backtest` | Register a `Broker` adapter for backtest |
+| `modules/paper.module.ts` | `--paper` | Register a `Broker` adapter for paper trading |
+| `modules/live.module.ts` | `--live` | Register a `Broker` adapter for live trading |
+| `modules/pine.module.ts` | `--pine` | Register an exchange schema for PineScript runs |
+| `modules/dump.module.ts` | `--dump` | Register an exchange schema for candle dumps |
+
+All files are optional — a missing module is a soft warning, not an error. Extensions `.ts`, `.mjs`, `.cjs` are tried automatically.
+
+## 🌍 Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Telegram notifications (required for --telegram)
+CC_TELEGRAM_TOKEN=your_bot_token_here
+CC_TELEGRAM_CHANNEL=-100123456789
+
+# Web UI server (optional, defaults shown)
+CC_WWWROOT_HOST=0.0.0.0
+CC_WWWROOT_PORT=60050
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_TELEGRAM_TOKEN` | — | Telegram bot token (from @BotFather) |
+| `CC_TELEGRAM_CHANNEL` | — | Telegram channel or chat ID |
+| `CC_WWWROOT_HOST` | `0.0.0.0` | UI server bind address |
+| `CC_WWWROOT_PORT` | `60050` | UI server port |
+
+
+## 🗂️ Project Structure
+
+```
+├── content/                  # Strategy entry points (.ts)
+│   └── feb_2026.strategy.ts
+├── docs/                     # Documentation
+│   ├── lib/                  # Auto-fetched library READMEs (via sync:lib)
+│   └── *.md                  # Backtest Kit how-to guides
+├── math/                     # PineScript indicator files (.pine)
+│   └── feb_2026.pine
+├── modules/                  # Side-effect module hooks (loaded automatically)
+│   ├── dump.module.ts        # Exchange schema for --dump mode
+│   └── pine.module.ts        # Exchange schema for --pine mode
+├── report/                   # Strategy research reports (.md)
+│   └── feb_2026.md
+├── scripts/
+│   └── fetch_docs.mjs        # Downloads library READMEs into docs/lib/
+├── CLAUDE.md                 # AI-agent guide for writing strategies
+└── package.json
+```
+
+## 📚 Updating Library Documentation
+
+```bash
+npm run sync:lib
+```
+
+Downloads the latest README files for all bundled libraries into `docs/lib/`. Run this after updating package versions or when you want fresh documentation available to the AI agent.