CLI Reference¶
sbam is a command-line application built with Cobra. Commands and flags follow standard CLI conventions. Configuration is resolved with the precedence: CLI flag > environment variable > config.yaml > built-in default.
Global Flags¶
| Flag | Description |
|---|---|
-h, --help |
Help for sbam |
-v, --version |
Version information |
Commands¶
schedule¶
The main intelligent charging workflow. Checks the forecast and battery residual capacity and decides whether to charge during the configured time windows.
sbam schedule [flags]
| Flag | Env var | Description | Default |
|---|---|---|---|
-k, --apikey |
APIKEY |
Solcast API key | — |
-u, --url |
URL |
Forecast URL(s), comma-separated | — |
-f, --cache_file_prefix |
CACHE_FILE_PREFIX |
Cache file name prefix | cached_forecast |
-n, --cache_forecast |
CACHE_FORECAST |
Enable forecast caching | false |
-l, --cache_time |
CACHE_TIME |
Cache TTL in seconds | 7200 |
-t, --crontab |
CRONTAB |
Cron expression (deprecated) | 0 0 0 0 0 (crontab disabled) |
--scheduler_mode |
SCHEDULER_MODE |
Scheduling mode (crontab, windows or optimize) |
crontab |
-H, --fronius_ip |
FRONIUS_IP |
Fronius inverter LAN IP | — |
--sunspec_type |
SUNSPEC_TYPE |
Inverter Modbus SunSpec model type (int_sf, float, auto) |
int_sf |
-s, --start_hr |
START_HR |
Charge window start (HH:MM) | 00:00 |
-e, --end_hr |
END_HR |
Charge window end (HH:MM) | 06:00 |
-m, --max_charge |
MAX_CHARGE |
Max grid charging power (W) | 3500 |
-S, --batt_reserve_start_hr |
BATT_RESERVE_START_HR |
Reserve window start (HH:MM) | start_hr value |
-E, --batt_reserve_end_hr |
BATT_RESERVE_END_HR |
Reserve window end (HH:MM) | end_hr value |
-c, --pw_consumption |
PW_CONSUMPTION |
Daily consumption (Wh) | 11000 |
-r, --pw_batt_reserve |
PW_BATT_RESERVE |
Battery reserve (Wh) | 4000 |
--batt_min_soc |
BATT_MIN_SOC |
Minimum SoC (%) kept by the inverter, for reserve_horizon: until_solar |
5 |
--grid_import_limit |
GRID_IMPORT_LIMIT |
Max site grid import (W) while charging from the grid (0 = disabled) |
0 |
--grid_charge_priority |
GRID_CHARGE_PRIORITY |
Under grid_import_limit: battery claims its charge first, loads uses only free power |
battery |
--grid_import_margin |
GRID_IMPORT_MARGIN |
Power (W) kept free under grid_import_limit |
200 |
--pw_base_load |
PW_BASE_LOAD |
Base load (W) for reserve_horizon: until_solar (0 = pw_consumption / 24) |
0 |
-L, --pw_lwt |
PW_LWT |
Lower threshold offset (Wh) | 0 |
-U, --pw_upt |
PW_UPT |
Upper threshold offset (Wh) | 0 |
-d, --defaults |
DEFAULTS |
Reconfigure inverter to defaults at cycle end | true |
--forecast_horizon |
FORECAST_HORIZON |
Forecast window mode | default |
--consumption_horizon |
CONSUMPTION_HORIZON |
Consumption model | full_day |
--windows |
WINDOWS |
Charge windows in YAML format | — |
--mqtt_enabled |
MQTT_ENABLED |
Enable MQTT | false |
--mqtt_broker |
MQTT_BROKER |
MQTT broker URL | — |
--mqtt_client_id |
MQTT_CLIENT_ID |
MQTT client ID | random |
--mqtt_username |
MQTT_USERNAME |
MQTT username | — |
--mqtt_password |
MQTT_PASSWORD |
MQTT password | — |
--mqtt_topic_prefix |
MQTT_TOPIC_PREFIX |
MQTT topic prefix | sbam |
--mqtt_ha_discovery |
MQTT_HA_DISCOVERY |
Enable HA MQTT discovery | true |
--mqtt_ha_discovery_prefix |
MQTT_HA_DISCOVERY_PREFIX |
HA discovery prefix | homeassistant |
--mqtt_tls_ca_file |
MQTT_TLS_CA_FILE |
MQTT TLS CA cert file | — |
--mqtt_tls_client_cert |
MQTT_TLS_CLIENT_CERT |
MQTT TLS client cert file | — |
--mqtt_tls_client_cert_key |
MQTT_TLS_CLIENT_CERT_KEY |
MQTT TLS client key file | — |
--mqtt_tls_insecure_skip |
MQTT_TLS_INSECURE_SKIP |
Skip TLS verification | false |
--ha_url |
HA_URL |
Home Assistant base URL (not needed in the HA add-on) | — |
--ha_token |
HA_TOKEN |
HA long-lived access token (secret; prefer the env var) | — |
--opt_price_entity |
OPTIMIZER_PRICE_ENTITY |
Nordpool price sensor entity ID (prices incl. VAT) | — |
--opt_consumption_entity |
OPTIMIZER_CONSUMPTION_ENTITY |
Household load power sensor entity ID | — |
--opt_ev_entity |
OPTIMIZER_EV_ENTITY |
Optional EV charger power sensor entity ID | — |
--opt_ev_guard_w |
OPTIMIZER_EV_GUARD_W |
EV power in W above which the battery is held instead of discharging into the car in self_consume hours; 0 disables [0, 50000] |
1000 |
--opt_history_days |
OPTIMIZER_HISTORY_DAYS |
Days of consumption history for the profile (1..30) | 10 |
--opt_battery_efficiency |
OPTIMIZER_BATTERY_EFFICIENCY |
Battery round-trip efficiency (0, 1] | 0.83 |
--opt_max_charge_rate_w |
OPTIMIZER_MAX_CHARGE_RATE_W |
Maximum battery charge rate in W (0, 30000] | 4500 |
--opt_max_discharge_rate_w |
OPTIMIZER_MAX_DISCHARGE_RATE_W |
Maximum battery discharge rate in W (0, 30000] | 4500 |
--opt_min_soc_pct |
OPTIMIZER_MIN_SOC_PCT |
Minimum battery SoC in percent [0, 100) | 7 |
--opt_vat_rate |
OPTIMIZER_VAT_RATE |
VAT rate as a fraction (0.25 = 25 %) | 0.25 |
--opt_sell_margin |
OPTIMIZER_SELL_MARGIN |
Sell margin in currency/kWh incl. VAT [-5, 10] | 0 |
--opt_min_gain |
OPTIMIZER_MIN_GAIN |
Minimum gain per hour before a charge or discharge replaces self-consumption; hold and standby need a tenth [0, 10] | 0.5 |
--opt_wear_cost |
OPTIMIZER_WEAR_COST |
Battery wear cost per kWh a forced charge or discharge moves [0, 5] | 0 |
--opt_purchase_surcharge |
OPTIMIZER_PURCHASE_SURCHARGE |
24 comma-separated surcharges incl. VAT, hour 00..23 | 24 × 0 |
--opt_dry_run |
OPTIMIZER_DRY_RUN |
Compute and publish the plan without writing to the inverter | true |
The --ha_* and --opt_* flags are used only with --scheduler_mode optimize. In config.yaml the same options live under the optimizer: map (--opt_price_entity → optimizer.price_entity). See Configuration → Cost Optimizer for valid ranges and the surcharge format. With scheduler_mode: optimize, a configuration error makes sbam schedule exit with code 1; in live mode it first attempts to restore inverter defaults.
optimize¶
Compute the cost-optimal battery plan for the current price horizon once, print it and exit. See Cost-optimized Dispatch.
sbam optimize [flags]
sbam optimize is always a dry run. It never writes to the inverter and publishes nothing over MQTT, whatever optimizer.dry_run says. Inverter writes only happen from sbam schedule with scheduler_mode: optimize.
| Flag | Env var | Description | Default |
|---|---|---|---|
--dry-run |
— | Print the plan only. Always on; --dry-run=false is rejected with exit code 1. Command-local, not a config key. |
true |
--output |
— | Output format: table or json |
table |
-u, --url |
URL |
Solcast forecast URL(s), comma-separated | — |
-k, --apikey |
APIKEY |
Solcast API key | — |
-H, --fronius_ip |
FRONIUS_IP |
Fronius inverter LAN IP | — |
-n, --cache_forecast |
CACHE_FORECAST |
Accepted for compatibility; the optimizer always uses the forecast cache | false |
-f, --cache_file_prefix |
CACHE_FILE_PREFIX |
Cache file name prefix | cached_forecast |
-l, --cache_time |
CACHE_TIME |
Cache TTL in seconds | 7200 |
-c, --pw_consumption |
PW_CONSUMPTION |
Daily consumption (Wh); static fallback for hours without history. Must be > 0. | 0 |
--ha_url |
HA_URL |
Home Assistant base URL (not needed in the HA add-on) | — |
--ha_token |
HA_TOKEN |
HA long-lived access token (secret; prefer the env var) | — |
--opt_price_entity |
OPTIMIZER_PRICE_ENTITY |
Nordpool price sensor entity ID (prices incl. VAT) | — |
--opt_consumption_entity |
OPTIMIZER_CONSUMPTION_ENTITY |
Household load power sensor entity ID | — |
--opt_ev_entity |
OPTIMIZER_EV_ENTITY |
Optional EV charger power sensor entity ID | — |
--opt_ev_guard_w |
OPTIMIZER_EV_GUARD_W |
EV power in W above which the battery is held instead of discharging into the car in self_consume hours; 0 disables [0, 50000] |
1000 |
--opt_history_days |
OPTIMIZER_HISTORY_DAYS |
Days of consumption history for the profile (1..30) | 10 |
--opt_battery_efficiency |
OPTIMIZER_BATTERY_EFFICIENCY |
Battery round-trip efficiency (0, 1] | 0.83 |
--opt_max_charge_rate_w |
OPTIMIZER_MAX_CHARGE_RATE_W |
Maximum battery charge rate in W (0, 30000] | 4500 |
--opt_max_discharge_rate_w |
OPTIMIZER_MAX_DISCHARGE_RATE_W |
Maximum battery discharge rate in W (0, 30000] | 4500 |
--opt_min_soc_pct |
OPTIMIZER_MIN_SOC_PCT |
Minimum battery SoC in percent [0, 100) | 7 |
--opt_vat_rate |
OPTIMIZER_VAT_RATE |
VAT rate as a fraction (0.25 = 25 %) | 0.25 |
--opt_sell_margin |
OPTIMIZER_SELL_MARGIN |
Sell margin in currency/kWh incl. VAT [-5, 10] | 0 |
--opt_min_gain |
OPTIMIZER_MIN_GAIN |
Minimum gain per hour before a charge or discharge replaces self-consumption; hold and standby need a tenth [0, 10] | 0.5 |
--opt_wear_cost |
OPTIMIZER_WEAR_COST |
Battery wear cost per kWh a forced charge or discharge moves [0, 5] | 0 |
--opt_purchase_surcharge |
OPTIMIZER_PURCHASE_SURCHARGE |
24 comma-separated surcharges incl. VAT, hour 00..23 | 24 × 0 |
--opt_dry_run |
OPTIMIZER_DRY_RUN |
Accepted; the command never writes regardless of its value | true |
Example (the token is read from HA_TOKEN; do not pass it as a flag in shell history):
export HA_TOKEN=<long-lived-token>
sbam optimize -H 192.168.1.100 -k "$APIKEY" -u "$SOLCAST_URL" -c 11000 \
--ha_url http://homeassistant.local:8123 \
--opt_price_entity sensor.nordpool_kwh_dk2_dkk_3_10_025 \
--opt_consumption_entity sensor.solarnet_power_load_consumed \
--opt_purchase_surcharge "0.52,0.52,0.52,0.52,0.52,0.52,0.78,0.78,0.78,0.78,0.78,0.78,0.78,0.78,0.78,0.78,0.78,2.04,2.04,2.04,2.04,0.78,0.78,0.78"
Table output (--output table, rows shortened here; the real output prints every hour):
sbam optimize - DRY RUN (nothing written to the inverter)
Run at 2026-10-05 10:20 +02:00 Horizon 36 h (until 2026-10-06 21:59)
Battery SoC 50.0 % capacity 10 000 Wh min SoC 7 % usable 4 300 Wh
Model efficiency 0.83 max charge 4 500 W max discharge 4 500 W
Prices sensor.nordpool_kwh_dk2_dkk_3_10_025 (DKK/kWh, incl. VAT) VAT 0.25 sell margin 0.10
Consumption sensor.solarnet_power_load_consumed
history 10 days; static fallback hours: none
PV Solcast (forecast cache)
START CONS Wh PV Wh BUY SELL ACTION RATE W SOC END %
Mon 10-05 10:00 333 1333 1.50 1.10 self_consume 0 58.1
Mon 10-05 16:00 500 0 1.50 1.10 hold 0 100.0
Mon 10-05 18:00 500 0 3.00 2.30 discharge 4325 51.6
Tue 10-06 04:00 500 0 0.80 0.54 charge 4482 62.8
Expected cost -30.74 DKK (import 17.45 - export 48.19 - terminal value 0.00)
Terminal value 0.00 DKK (0 Wh left above min SoC x 0.83 x mean buy 1.63)
Decision hour 0: self_consume 0 W - optimizer_self_consume_no_gain
Reasons optimizer_self_consume_no_gain
STARTis local time. On DST days, repeated or skipped hours get the UTC offset appended, e.g.Sun 10-26 02:00+02.static fallback hoursshowsnone,some, see log (optimizer_consumption_static_fallback)orall (optimizer_consumption_entity_not_found).PVshowsforecast cache, or that missing or stale forecast hours are counted as 0 Wh.
Fallback output. When no usable plan can be computed, no table is printed:
sbam optimize - DRY RUN (nothing written to the inverter)
Run at 2026-10-05 10:20 +02:00
FALLBACK: optimizer_fallback_missing_prices - inverter defaults would be restored
Input price: no price for the current hour
Battery SoC 50.0 %
Reasons optimizer_fallback_missing_prices
JSON output (--output json) prints the same object as the <prefix>/plan MQTT topic; see Optimizer Plan Topic. On fallback, hours is empty and the cost fields are null.
Exit codes
| Code | Meaning |
|---|---|
0 |
Plan computed and printed. |
1 |
Configuration error (all problems are listed in one message), invalid --output, or --dry-run=false. |
2 |
Optimizer fallback: the command ran, but no usable plan could be computed. The output names the reason. |
estimate¶
Print the solar forecast and battery storage power.
sbam estimate [flags]
| Flag | Env var | Description | Default |
|---|---|---|---|
-k, --apikey |
APIKEY |
Solcast API key | — |
-u, --url |
URL |
Forecast URL(s), comma-separated | — |
-f, --cache_file_prefix |
CACHE_FILE_PREFIX |
Cache file name prefix | cached_forecast |
-n, --cache_forecast |
CACHE_FORECAST |
Enable forecast caching | false |
-l, --cache_time |
CACHE_TIME |
Cache TTL in seconds | 7200 |
--forecast_horizon |
FORECAST_HORIZON |
Forecast horizon mode | default |
-H, --fronius_ip |
FRONIUS_IP |
Fronius inverter LAN IP | — |
configure¶
Connect to the Fronius inverter via Modbus and set charging parameters.
sbam configure [flags]
| Flag | Description |
|---|---|
-d, --defaults |
Set DEFAULTS |
-f, --force_charge |
Set FORCE_CHARGE |
-H, --fronius_ip |
Fronius inverter LAN IP |
-p, --power |
Percent of nominal power |
--sunspec_type |
Inverter Modbus SunSpec model type (int_sf, float, auto). Default int_sf |
Debug Logs¶
Set the DEBUG environment variable to true to increase log level:
export DEBUG=true
sbam schedule
# 2026-04-29T11:15:19+02:00 DEBUG Debug Logs activated: true
Log Format¶
Set LOG_TYPE to console (human-friendly) or json (machine-readable):
export LOG_TYPE=json
export DEBUG=true
sbam schedule
# {"level":"debug","ts":"2026-04-29T11:16:24+02:00","msg":"Debug Logs activated: true"}
In scheduler_mode: optimize, each run writes exactly one optimizer run Info line. Fallbacks and degraded inputs add one Warn line each:
INFO optimizer run {"dry_run": true, "action": "hold", "rate_w": 0, "reason": "optimizer_hold_for_later_peak", "reasons": ["optimizer_hold_for_later_peak"], "expected_cost": 41.87, "terminal_value": 1.93, "horizon_h": 34, "soc_pct": 52.0, "duration_ms": 312}
INFO dry run: no Modbus registers written {"action": "hold", "rate_w": 0, "registers": "..."}
WARN optimizer fallback: inverter defaults restored {"reason": "optimizer_fallback_ha_unreachable", ...}
WARN optimizer degraded input {"reason": "optimizer_consumption_static_fallback", "hours": [3, 4]}
Charge Windows¶
Charge windows can be defined as a single legacy window (--start_hr, --end_hr, --max_charge) or as a multi-window list (--windows or the windows: key in config.yaml). The two forms are mutually exclusive.
Legacy single window:
Time windows can span midnight:
--start_hr 22:00 --end_hr 06:00
With optional reserve window:
--batt_reserve_start_hr 23:00 --batt_reserve_end_hr 05:00
Multi-window list (YAML):
--windows '[{name: night, start: "02:00", end: "06:00", max_charge: 3500, forecast_horizon: tomorrow}, {name: midday, start: "12:00", end: "15:00", max_charge: 2000}]'
Equal start/end values are invalid. Overlapping windows are rejected at startup.
Each window can also include a weekdays field for day-of-week filtering and
the weekday_feature flag controls the feature globally. See the
Weekday Filtering guide for the format, start-day model, and
worked examples.