Command-Line Interface (CLI)

Using the behaviorsim command-line tool for validation and batch simulation.

BehaviorSim provides a native CLI tool executable as behaviorsim.

Overview

terminal

behaviorsim --help

1. behaviorsim validate

Validates a YAML or JSON configuration file against the schema before execution:

terminal

behaviorsim validate config.yaml

2. behaviorsim run

Executes a simulation from a configuration file and outputs results to stdout or a file:

terminal

# Output to CSV
behaviorsim run config.yaml -o traces.csv --interactions 100 --seed 42

# Output to Apache Parquet
behaviorsim run config.yaml -o traces.parquet --sequences 50

Execution Flags

Flag	Short	Description
--output	-o	Target file path (.csv, .json, or .parquet). Default: stdout
--seed	-	Override RNG seed integer
--interactions	-	Number of interaction steps per sequence
--sequences	-	Number of sequences to generate
--profile	-	Target single profile override

Configuration File Examples

A validated YAML configuration file conforming to the SimulationConfig schema:

simulation.yaml

# simulation.yaml
version: "1.0"
states:
  - name: "Active"
    description: "Engaged active state"
  - name: "Idle"
    description: "Passive idle state"
transition_matrix:
  - [0.7, 0.3]
  - [0.2, 0.8]
profiles:
  - name: "default_user"
    state_emissions:
      Active:
        latency_ms:
          distribution: "normal"
          params:
            loc: 120.0
            scale: 25.0
      Idle:
        latency_ms:
          distribution: "exponential"
          params:
            scale: 500.0
simulation:
  num_interactions: 100
  num_sequences: 1
  seed: 42
  initial_state: "Active"

Equivalent JSON configuration file supported by both behaviorsim validate and behaviorsim run:

simulation.json

{
  "version": "1.0",
  "states": [
    { "name": "Active", "description": "Engaged active state" },
    { "name": "Idle", "description": "Passive idle state" }
  ],
  "transition_matrix": [
    [0.7, 0.3],
    [0.2, 0.8]
  ],
  "profiles": [
    {
      "name": "default_user",
      "state_emissions": {
        "Active": {
          "latency_ms": {
            "distribution": "normal",
            "params": { "loc": 120.0, "scale": 25.0 }
          }
        },
        "Idle": {
          "latency_ms": {
            "distribution": "exponential",
            "params": { "scale": 500.0 }
          }
        }
      }
    }
  ],
  "simulation": {
    "num_interactions": 100,
    "num_sequences": 1,
    "seed": 42,
    "initial_state": "Active"
  }
}

PreviousPython API Reference

NextREST API Overview