Experiments and CLI

Experiment modules

For CLI-driven runs, export a default experiment created with defineExperiment from @thecommandcat/fbtf/experiment.

An experiment module is the bridge between a reusable runner configuration and a repeatable local run. It is the right place to wrap a market, strategy, feed, and broker into one named unit.

Run config

The CLI expects one required config file.

{
  "modulePath": "./examples/07-minimal-experiment.ts",
  "reportMode": "human",
  "runId": "minimal-experiment",
  "params": {},
  "config": {}
}

This keeps the CLI flow simple: one file points at one experiment module and provides the run inputs in one place.

Run it

npx @thecommandcat/fbtf run ./minimal-experiment.config.json

In practice this is useful when you want a repeatable local run that does not depend on remembering a pile of flags.

Repo examples

The repository keeps a very small curated example set:

• examples/01-minimal-backtest.ts
• examples/03-cost-slippage-comparison.ts
• examples/07-minimal-experiment.ts
• examples/09-databento-ema-bracket.ts

These examples live in the repo and are not shipped in the npm tarball.

When to use experiments

Use experiment modules when:

• you want repeatable local runs
• you want config-driven variation without rewriting the module
• you want a clean boundary between library API usage and runnable example workflows

Use the direct library API when:

• you are embedding fbtf inside another application
• you do not need the CLI workflow
• you want total control over orchestration in code