📟 @backtest-kit/cli

// src/index.mjs — registers schemas via backtest-kit; @backtest-kit/cli just runs it
import { addStrategySchema, addExchangeSchema, addFrameSchema } from 'backtest-kit';
import ccxt from 'ccxt';

addExchangeSchema({
  exchangeName: 'binance',
  getCandles: async (symbol, interval, since, limit) => {
    const exchange = new ccxt.binance();
    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),
});

addFrameSchema({ frameName: 'feb-2024', interval: '1m',
  startDate: new Date('2024-02-01'), endDate: new Date('2024-02-29') });

addStrategySchema({ strategyName: 'my-strategy', interval: '15m',
  getSignal: async (symbol) => null }); // return a signal or null
Copy

Wire it into package.json once and the positional path never changes:

{
  "scripts": {
    "backtest": "npx @backtest-kit/cli --backtest ./src/index.mjs",
    "paper":    "npx @backtest-kit/cli --paper    ./src/index.mjs",
    "start":    "npx @backtest-kit/cli --live     ./src/index.mjs"
  },
  "dependencies": { "@backtest-kit/cli": "latest", "backtest-kit": "latest", "ccxt": "latest" }
}
Copy

npm run backtest -- --symbol BTCUSDT --ui --telegram   # add integrations with flags
Copy

Positional argument (required): path to your strategy entry point file — set once in package.json scripts. Tool-specific flags (--pine, --dump, --pnldebug, --docker, …) are documented in their sections below.

Backtest (--backtest) — runs against historical candles via a registered FrameSchema. Before running, the CLI removes the report, log, markdown, and agent folders from the strategy's dump/ dir, then warms the candle cache for every interval in --cacheInterval; subsequent runs reuse the cache with no API calls. --noCache skips warming, --noFlush keeps output folders.

{ "scripts": { "backtest": "npx @backtest-kit/cli --backtest --symbol ETHUSDT --strategy my-strategy --exchange binance --frame feb-2024 --cacheInterval \"1m, 15m, 1h, 4h\" ./src/index.mjs" } }
Copy

Paper (--paper) — connects to the live exchange but places no real orders. Identical code path to live — the safe way to validate a strategy.

{ "scripts": { "paper": "npx @backtest-kit/cli --paper --symbol BTCUSDT ./src/index.mjs" } }
Copy

Live (--live) — deploys a real bot. Requires exchange API keys in .env. Combine with --ui --telegram for a monitored deployment.

{ "scripts": { "start": "npx @backtest-kit/cli --live --ui --telegram --symbol BTCUSDT ./src/index.mjs" } }
Copy

Each positional argument is a separate strategy entry point. Before loading them the CLI removes the report/log/markdown/agent folders from each entry point's dump/ (skip with --noFlush). All files load without changing process.cwd() — .env is read from the working directory only. After loading, addWalkerSchema is called automatically using the exchange and frame registered by the strategy files. If no frame is registered, the CLI falls back to the last 31 days from Date.now() with a warning.

Output: no flag → print Markdown report to stdout; --json / --markdown → save and exit. Module hook: ./modules/walker.module loads automatically before the comparison (.ts/.mjs/.cjs tried in order).

Unlike the trading modes it does not call Backtest/Live/Walker.background, pick a symbol, warm the cache, or resolve a strategy/exchange/frame — the entry point decides what to run. Exactly one positional entry point is required (Entry point is required otherwise). process.cwd() changes to the entry-point directory and its local .env overrides the root .env.

Although the CLI starts nothing itself, any Backtest/Live/Walker run your entry point launches is still managed: the process exits once listenDone* reports completion, the first Ctrl+C stops every active run via *.list()/*.stop(), a second force-quits. ./modules/main.module loads automatically before the entry point.

{ "scripts": { "main": "npx @backtest-kit/cli --main ./tools/fetch_fear_and_greed.ts" } }
Copy

// src/multi-symbol.mjs
import { addExchangeSchema, addFrameSchema, addStrategySchema, Backtest, warmCandles } from "backtest-kit";
import ccxt from "ccxt";

addExchangeSchema({ exchangeName: "binance",
  getCandles: async (symbol, interval, since, limit) => {
    const exchange = new ccxt.binance();
    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: (s, p) => p.toFixed(2), formatQuantity: (s, q) => q.toFixed(8) });

addFrameSchema({ frameName: "feb-2026", interval: "1m",
  startDate: new Date("2026-02-01"), endDate: new Date("2026-02-28") });
addStrategySchema({ strategyName: "my-strategy", interval: "15m", getSignal: async () => null });

// Decide the symbol set yourself — UI, database, API, or a list.
for (const symbol of ["BTCUSDT", "ETHUSDT", "SOLUSDT", "BNBUSDT", "XRPUSDT"]) {
  // optional: await warmCandles({ exchangeName: "binance", interval: "1m", symbol, from, to });
  Backtest.background(symbol, { strategyName: "my-strategy", exchangeName: "binance", frameName: "feb-2026" });
}
Copy

npx @backtest-kit/cli --backtest --entry ./src/multi-symbol.mjs
Copy

The same shape works for --live --entry / --paper --entry (call Live.background() per symbol with your broker adapter).

// modules/pine.module.ts  (same shape for editor/dump/pnldebug.module; brokerdebug registers a Broker instead)
import { addExchangeSchema } from "backtest-kit";
import ccxt from "ccxt";

addExchangeSchema({
  exchangeName: "my-exchange",
  getCandles: async (symbol, interval, since, limit) => {
    const exchange = new ccxt.bybit({
      apiKey: process.env.BYBIT_API_KEY, secret: process.env.BYBIT_API_SECRET, 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: (s, p) => p.toFixed(2), formatQuantity: (s, q) => q.toFixed(8),
});
Copy

# .env (loaded root-first, then next to the target file)
BYBIT_API_KEY=xxx
BYBIT_API_SECRET=yyy
Copy

--limit must cover indicator warmup bars — rows before warmup show N/A. Positional: path to the .pine file. Exchange via pine.module (see convention above). Required plot form:

//@version=5
indicator("MyIndicator", overlay=true)
plot(close,    "Close",    display=display.data_window)
plot(position, "Position", display=display.data_window)
Copy

Output (stdout, or --markdown/--json/--jsonl to <pine-dir>/dump/):

| Close | Position | timestamp |
| --- | --- | --- |
| 112871.28 | -1.0000 | 2025-09-22T15:00:00.000Z |
| 112736.00 |  0.0000 | 2025-09-22T18:30:00.000Z |
| 112653.90 |  1.0000 | 2025-09-22T22:15:00.000Z |
Copy

The CLI loads ./modules/editor.module if present (register your exchange, same as pine.module), starts the @backtest-kit/ui server on CC_WWWROOT_PORT (default 60050), and opens the editor in your browser. Ctrl+C stops it. Env: CC_WWWROOT_HOST (default 0.0.0.0), CC_WWWROOT_PORT (default 60050).

Exchange via dump.module (see convention above), searched in the current working directory. No flag → print to stdout.

Columns: min (1-based offset), timestamp, close, pnl% (signed, vs entry), peak% (highest so far, ≥0), drawdown% (lowest so far, ≤0). Exchange via pnldebug.module (convention above).

Symbol: BTCUSDT | Direction: short | PriceOpen: 64069.50 | From: 2025-02-25T00:00:00.000Z | Minutes: 120
  min | timestamp                 |        close  |    pnl%  |   peak%  | drawdown%
    1 | 2025-02-25T00:01:00.000Z  |      64020.10 |   +0.08% |   +0.08% |     0.00%
    2 | 2025-02-25T00:02:00.000Z  |      64105.30 |   -0.06% |   +0.08% |    -0.06%
  120 | 2025-02-25T02:00:00.000Z  |      63200.00 |   +1.36% |   +1.36% |    -0.06%
Copy

--commit values → hook: signal-open→onSignalOpenCommit, signal-close→onSignalCloseCommit, partial-profit→onPartialProfitCommit, partial-loss→onPartialLossCommit, average-buy→onAverageBuyCommit, trailing-stop→onTrailingStopCommit, trailing-take→onTrailingTakeCommit, breakeven→onBreakevenCommit.

The CLI loads ./modules/brokerdebug.module, fetches the last candle for --symbol, derives a synthetic payload from currentPrice (TP = +2%, SL = −2%), and calls the selected hook once; exits 0 on success. The module registers a Broker adapter (Broker.useBrokerAdapter(...) + Broker.enable()), not an exchange.

For each positional entry point the CLI resolves its directory and removes from <entry-dir>/dump/: report (backtest .jsonl), log (log.jsonl), markdown (exported reports), agent (agent outlines). Candle cache (dump/data/) and AI forecast outlines (dump/outline/) are not removed.

backtest-kit-project/
├── package.json              # pre-configured with all backtest-kit deps
├── CLAUDE.md                 # AI-agent guide for writing strategies
├── content/feb_2026.strategy.ts   # example strategy entry point
├── math/feb_2026.pine             # example PineScript indicator
├── modules/{dump,pine}.module.ts  # exchange schemas for --dump / --pine
├── report/feb_2026.md             # example research report
├── docs/{...}.md + docs/lib/      # guides + fetched library READMEs
└── scripts/fetch_docs.mjs         # downloads library READMEs into docs/lib/
Copy

After scaffolding the CLI runs scripts/fetch_docs.mjs, downloading the latest READMEs for backtest-kit, @backtest-kit/graph, @backtest-kit/pinets, @backtest-kit/cli, garch, volume-anomaly, agent-swarm-kit, functools-kit into docs/lib/. Re-run anytime with node ./scripts/fetch_docs.mjs or npm run sync:lib.

1. command: in docker-compose.yaml — pin mode and flags directly; the entrypoint forwards all args to the CLI unchanged:

command: [--live, --symbol, TRXUSDT, --strategy, feb_2026_strategy, --exchange, ccxt-exchange, ./content/feb_2026/feb_2026.strategy.ts, --ui]
Copy

2. Inline env vars — MODE + STRATEGY_FILE on the command line, no file edits:

ResolveService runs, before executing your entry point:

process.chdir(path.dirname(entryPoint))                         // cwd → strategy directory
dotenv.config({ path: rootDir + '/.env' })                      // root .env first
dotenv.config({ path: strategyDir + '/.env', override: true })  // strategy .env overrides
Copy

monorepo/
├── package.json              # root scripts (one per strategy)
├── .env                      # shared API keys
└── strategies/
    ├── oct_2025/
    │   ├── index.mjs              # registers exchange/frame/strategy schemas
    │   ├── .env                   # overrides root .env for this strategy
    │   ├── modules/{live,paper,backtest}.module.mjs  # broker adapters (optional)
    │   ├── template/              # custom Mustache templates (optional)
    │   └── dump/                  # auto-created: candle cache + reports
    └── dec_2025/ …
Copy

Each run produces its own dump/ — easy to compare results across periods, by inspection or by pointing an AI agent at a specific folder.

Both barrel and deep-subpath imports are supported. Add a matching paths entry to tsconfig.json so the editor resolves them:

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "paths": { "logic": ["./logic/index.ts"], "logic/*": ["./logic/*"], "math": ["./math/index.ts"], "math/*": ["./math/*"], "utils": ["./utils/index.ts"], "utils/*": ["./utils/*"] }
  },
  "include": ["./logic", "./math", "./utils", "./content", "./modules"]
}
Copy

// live.module.mjs
import { Broker } from 'backtest-kit';
import { myExchange } from './exchange.mjs';

class MyBroker {
  async onSignalOpenCommit({ symbol, priceOpen, direction }) { await myExchange.openPosition(symbol, direction, priceOpen); }
  async onSignalCloseCommit({ symbol, priceClosed })        { await myExchange.closePosition(symbol, priceClosed); }
  async onPartialProfitCommit({ symbol, cost, currentPrice }) { await myExchange.createOrder({ symbol, side: 'sell', quantity: cost / currentPrice }); }
  async onAverageBuyCommit({ symbol, cost, currentPrice })    { await myExchange.createOrder({ symbol, side: 'buy',  quantity: cost / currentPrice }); }
}

Broker.useBrokerAdapter(MyBroker);
Broker.enable();
Copy

All methods are optional; unimplemented hooks are silently skipped. TypeScript: implement Partial<IBroker> with typed payloads (BrokerSignalOpenPayload, etc.).

setup() registers all 15 persistence adapters in one call, reading connection params from env (or passed explicitly):

// config/setup.config.ts
import { setup } from '@backtest-kit/mongo';
setup(); // or setup({ CC_MONGO_CONNECTION_STRING, CC_REDIS_HOST, CC_REDIS_PORT, CC_REDIS_PASSWORD })
Copy

CC_MONGO_CONNECTION_STRING=mongodb://localhost:27017/backtest-kit
CC_REDIS_HOST=127.0.0.1
CC_REDIS_PORT=6379
Copy

No strategy-code changes — adapters are wired transparently before the first persistence call.

Use it to: wire microfrontends in a monorepo (pre-load sibling packages, hydrate a shared DI container); wait for a DB connection so the backtest fails fast instead of mid-run; warm caches / external APIs (instruments, calendar, fee tables); run schema migrations before signals flow.

Exactly one export style — never both (if both present, default wins):

// config/loader.config.ts — default export (preferred)
export default async () => { await mongoose.connect(process.env.CC_MONGO_CONNECTION_STRING!); await redis.ping(); };
// — or named export
export const loader = async () => { /* … */ };
Copy

@backtest-kit/mongo's setup() registers adapters synchronously but doesn't block on the connection; gate the run on a real connection here. To stitch microfrontends: import "@my-org/brokers"; import "@my-org/signals"; (the @my-org alias is declared in alias.config).

// config/alias.config.ts — named export
export const ccxt = require("./stubs/ccxt.stub.cjs");
// config/alias.config.cjs — default export
module.exports = { ccxt: require("./stubs/ccxt.stub.cjs") };
Copy

It may also export an async factory the CLI awaits before strategy code runs — handy for ESM-only modules that require() would throw on:

// async factory (default export); or `export const loader = async () => ({...})`
export default async () => ({ nanoid: await import("nanoid"), "p-limit": await import("p-limit") });
Copy

Both styles supported, never both at once (default wins). When strategy code calls require("ccxt"), the loader checks the alias table first — no monkey-patching of node_modules. Applies to all modules in the process (not per-strategy).

By default the UI shows all exchange symbols. Override with a config/symbol.config (resolution: strategy dir → project root → package default):

// config/symbol.config.ts
export const symbol_list = [
  { icon: "/icon/btc.png", logo: "/icon/128/btc.png", symbol: "BTCUSDT", displayName: "Bitcoin",  color: "#F7931A", priority: 50, description: "Bitcoin — the first and most popular cryptocurrency" },
  { icon: "/icon/eth.png", logo: "/icon/128/eth.png", symbol: "ETHUSDT", displayName: "Ethereum", color: "#6F42C1", priority: 50, description: "Ethereum — a blockchain platform for smart contracts" },
];
Copy

Defaults (override per strategy):

// config/notification.config.ts
export default { signal: true, risk: true, info: true, breakeven: true, common_error: true, critical_error: true, validation_error: true, strategy_commit: true, partial_loss: false, partial_profit: false, signal_sync: false };
Copy

By default messages render from Mustache templates (template/*.mustache). Export an object with any subset of get*Markdown methods (each gets the event payload, returns Promise<string>); unimplemented ones fall back to the template.

// config/telegram.config.ts
import { IStrategyTickResultOpened, IStrategyTickResultClosed, RiskContract } from "backtest-kit";
export default {
  async getOpenedMarkdown(e: IStrategyTickResultOpened) { return `**Opened** ${e.symbol} at ${e.priceOpen}`; },
  async getClosedMarkdown(e: IStrategyTickResultClosed) { return `**Closed** ${e.symbol} at ${e.priceClosed}`; },
  async getRiskMarkdown(e: RiskContract)                { return `**Risk rejected** ${e.symbol}`; },
};
Copy

Methods → event types: getOpenedMarkdown/getClosedMarkdown/getScheduledMarkdown/getCancelledMarkdown (IStrategyTickResult*), getRiskMarkdown (RiskContract), getPartialProfitMarkdown/getPartialLossMarkdown/getBreakevenMarkdown/getTrailingTakeMarkdown/getTrailingStopMarkdown/getAverageBuyMarkdown (the matching *Commit), getSignalOpenMarkdown/getSignalCloseMarkdown (SignalOpen/CloseContract), getCancelScheduledMarkdown/getClosePendingMarkdown (*Commit), getSignalInfoMarkdown (SignalInfoContract).

run() can be called only once per process — a second call throws "Should be called only once". mode: "backtest" | "paper" | "live".

Backtest: entryPoint, symbol ("BTCUSDT"), strategy (first registered), exchange (first registered), frame (first registered), cacheInterval (["1m","15m","30m","1h","4h"]), noCache (false), noFlush (false), verbose (false).

Paper / Live: entryPoint, symbol ("BTCUSDT"), strategy (first registered), exchange (first registered), verbose (false).