Reference · v0.0.1

Bela CLI reference

The @bela/cli package ships one binary, bela, with three real subcommands — init, train, eval — plus help. All flag names and defaults below are verified against packages/cli/src/cli.ts.

bela init [dir]

Scaffolds a starter agent.tools.mjs in dir (defaults to the current directory; also accepts --dir <path>).

• Creates dir (and any missing parent directories) if it doesn't exist.
• Refuses to overwrite: throws refusing to overwrite: <path> already exists if agent.tools.mjs is already present in dir.
• The scaffold defines two example entities (Room, Guest), a confirm: true tool (sendCheckoutReminder), and a roles-gated tool (bookRoom) with a number() and a dateRange() param — a working reference for all four param/tool features documented in the integration guide.

$ bela init ./my-agent
created ./my-agent/agent.tools.mjs

Exit code 0 on success; non-zero (uncaught error printed to stderr) if the file already exists or the directory can't be created.

bela train --config <path>

Trains a model from a config file and saves it if it clears the quality gate.

Behavior:

1. Loads the config (import(configPath), so .mjs configs run directly; see the tsx note below for .ts configs).
2. Runs trainModel(config, { seed, perTool, epochs }) and prints the metrics line: intentAcc=<n> slotExact=<n> testCount=<n>.
3. Checks meetsGate(metrics, { intentAcc: minIntent, slotExact: minSlot }).
4. If the gate passes, or --force is set, calls saveModel(model, out) and prints saved model to <out> (with a (gate failed, --force) suffix if it was forced).
5. If the gate fails and --force wasn't given, nothing is saved and it prints gate failed (need intentAcc>=<n>, slotExact>=<n>); not saving. Use --force to override.

Exit code: the bela bin (packages/cli/bin/bela.mjs) calls process.exit(1) when train did not save (gate failed, no --force); otherwise exit code 0. Any thrown error (bad config path, --config missing) is caught at the top level, printed to stderr, and also exits 1.

bela eval --config <path> --model <path>

Re-evaluates a previously saved model against a freshly generated test set from the same config.

Behavior: loads the config and model, re-collects entity values (collectEntityValues), regenerates a dataset with the given seed and --per-tool (generateDataset), evaluates the loaded model against the test split, and prints the same metrics line as train: intentAcc=<n> slotExact=<n> testCount=<n>.

As of P4, loadModel validates the artifact's shape before returning it — a corrupted or hand-edited model file fails fast with a message like invalid model artifact: intents must be a string array (also checked: version, params, tagLabels, positive-integer buckets/dim, and that each embedding/weight/bias array is exactly the expected length) — instead of crashing deep inside evaluate/predict with an opaque error.

Exit code 0 on success; a thrown error (missing flags, invalid model artifact, bad config) is caught at the top level and exits 1.

bela help

Prints the built-in usage text (also shown when no command, or an unknown command, is given):

bela — tiny self-training agent CLI

Usage:
  bela init [dir]              scaffold a starter agent.tools.mjs
  bela train --config <path>   train a model from a config
      [--out <path>] [--seed <n>] [--per-tool <n>] [--epochs <n>]
      [--min-intent <n>] [--min-slot <n>] [--force]
  bela eval --config <path> --model <path>   evaluate a saved model
      [--seed <n>] [--per-tool <n>]
  bela help                    show this message

Exit code 0.

.mjs vs. TypeScript configs

runInit scaffolds agent.tools.mjs, and both train/eval load the config with a plain dynamic import() of the given path (pathToFileURL(configPath).href) — no TypeScript transform happens in the CLI itself. That means:

• A .mjs (or .js with "type": "module" in scope) config runs directly — this is the supported default and what bela init scaffolds.
• A .ts config is not transpiled by the CLI; running bela train --config agent.tools.ts will fail with a syntax/module error under plain node. If you want to write your config in TypeScript, run the CLI through npx tsx (e.g. npx tsx node_modules/.bin/bela train --config agent.tools.ts … once published, or the npx tsx packages/cli/src/cli.ts equivalent inside this monorepo) so .ts imports are transpiled on the fly — the CLI's own logic doesn't change either way, only how the config file gets loaded.

Worked session

This is a real transcript — bela init, then train, then eval — run through the actual CLI functions (numbers are not fabricated; see intentAcc/slotExact/testCount below):

$ bela init ./my-agent
created ./my-agent/agent.tools.mjs

$ vim ./my-agent/agent.tools.mjs   # replace the two TODO resolve() calls
                                    # with real queries against your DB/API

$ bela train --config ./my-agent/agent.tools.mjs --out ./my-agent/bela-model.json
intentAcc=0.9891 slotExact=1.0000 testCount=92
saved model to ./my-agent/bela-model.json

$ bela eval --config ./my-agent/agent.tools.mjs --model ./my-agent/bela-model.json
intentAcc=0.9891 slotExact=1.0000 testCount=92

The unedited starter config (two entities, two tools) already clears the default gate (intentAcc>=0.9, slotExact>=0.8) out of the box — real projects with more tools/utterances should expect similar or better numbers once entity resolve() is wired to real data, since more/varied rows give the model more to train and test on. If a change to your config drops metrics below the gate, train refuses to save (see above) — either fix your utterances/entities or explicitly --force a save while iterating.

Exit codes summary