bim-energy

Run whole-building energy simulations and compliance checks from the command line. Accepts gbXML and OpenStudio .osm files. Requires NREL OpenStudio CLI — one install command handles that.

Run energy simulations and PHIUS CORE 2024 compliance checks. No cloud, no account.

Install dependency

bim-energy requires the NREL OpenStudio CLI:

bim energy install

To preview what will be installed first:

bim energy install --dry_run true

Verbs

Verb	What it does
bim energy version	Driver version
bim energy doctor	Check bim-energy environment: OpenStudio CLI install, EnergyPlus version, install path
bim energy run --in FILE [--engine ENGINE] [--weather FILE]	Run an energy simulation via NREL OpenStudio CLI; returns {eui_kbtu_sf_yr, annual_kwh, peak_kw, end_uses[]}
bim energy phius.check --in FILE [--target TARGET] [--path PATH]	PHIUS CORE 2024 compliance check; returns {compliant, checks: [{name, target, actual, pass}]}
bim energy install [--dry-run] [--interactive]	Download and install NREL OpenStudio CLI (required for bim energy run)

run

bim energy run --in <file.gbxml|file.osm> [--engine openstudio] [--weather <file.epw>]

Runs an energy simulation against the input model. Returns:

{
  "ok": true,
  "result": {
    "eui_kbtu_sf_yr": 42.3,
    "annual_kwh": 187400,
    "peak_kw": 48.2,
    "end_uses": [
      { "name": "heating", "kwh": 34200 },
      { "name": "cooling", "kwh": 51900 }
    ]
  }
}

• --engine — simulation engine; only openstudio is supported (default)
• --weather — path to an .epw weather file; overrides any weather file embedded in the model

phius.check

bim energy phius.check --in <file.gbxml> [--target phius-core-2024] [--path performance]

Runs a PHIUS CORE 2024 compliance check against the input file. Returns:

{
  "ok": true,
  "result": {
    "compliant": false,
    "checks": [
      { "name": "source_energy_heating", "target": 4.42, "actual": 5.1, "pass": false },
      { "name": "source_energy_cooling", "target": 4.42, "actual": 3.8, "pass": true }
    ]
  }
}

• --target — compliance target; only phius-core-2024 supported
• --path — compliance path: performance (default) or prescriptive

doctor

bim energy doctor

Checks the local environment for the OpenStudio CLI and EnergyPlus:

{
  "ok": true,
  "result": {
    "openstudio": { "found": true, "version": "3.8.0", "path": "C:\\..." },
    "energyplus": { "found": true, "version": "23.2.0" }
  }
}

Failed checks include a hint field with the fix command.

Gotchas

• gbXML export from Revit requires the Energy Settings to be configured before export.
• .osm files from OpenStudio must include a weather file or --weather must be provided.
• phius.check validates the gbXML structure directly; it does not require a full simulation run.
• Simulation runs can take 30-120 seconds depending on model complexity.

For agent use: /energy/llms.txt